Running Qodana Static Analysis Locally with the CLI

Static analysis—examining source code for bugs, style violations, and security issues without executing it—often behaves like a black box: developers run inspections in their IDE, CI runs a different configuration, and the results never match. The useful takeaway is that you can close this gap locally by running Qodana through its command-line interface against the same qodana.yaml configuration your pipeline uses. This guide covers the prerequisites, the minimal configuration, and how to verify the scan actually worked.

What you need before running a scan

Qodana executes static analysis inside a container, so your machine must provide a Docker-compatible runtime. Docker Desktop, Colima, and Podman are common choices. If the Docker daemon is not running, the CLI cannot start the analysis container.

You also need the Qodana CLI installed and available on your PATH. The CLI pulls the correct analysis image, mounts your project, and manages the report. You do not need a full JetBrains IDE installed to use it.

Because the analysis runs in a container with its own inspection engine, the first scan on a large repository can consume significant memory. On machines with limited RAM, close other memory-heavy applications before the initial run.

Creating a minimal qodana.yaml

Qodana reads its configuration from a qodana.yaml file in the project root. This file controls which inspection profile to use, which paths to skip, and how aggressively to report issues. Teams that already maintain JetBrains inspection profiles can reference them here so the CLI and the IDE apply the same rules.

The following example shows a conservative starting point. Treat the exact schema as version-dependent and confirm the supported keys against the Qodana documentation for the version you are using.

version: "1.0"
profile:
  name: qodana.recommended
exclude:
  - name: GeneratedCode
    paths:
      - build
      - dist

Replace qodana.recommended with the profile your team actually uses. The exclude block prevents the scanner from wasting time on build artifacts. A syntax error in this file—such as an indentation mistake or an unsupported key—can cause the container to fail at startup or silently skip inspections.

Running the scan

Open a terminal in the project root and run:

qodana scan

This command typically runs with standard user permissions, assuming your container runtime is configured for your user account. It needs read access to your project directory and write access to create the results folder. The CLI will pull the analysis image if it is not cached locally, then start the container.

When the command finishes, it should create a directory named qodana-team-results in your project root. This directory contains the raw analysis data. If the directory is absent, the scan did not complete successfully.

Reviewing results without leaving the terminal

To inspect the findings, run:

qodana report

This launches a local web server and opens an HTML report in your browser. The report groups issues by file, severity, and inspection type. You can use it to triage findings before committing code.

A practical validation step is to change one inspection setting in qodana.yaml—for example, adding an excluded path or adjusting an inspection level—then run qodana scan again. If the next report reflects the change, you have confirmed that the configuration file is being read and applied.

Recovery options when things go wrong

If the container fails to start, first verify that your Docker-compatible runtime is active. A stopped daemon is the most common cause.

If the scan starts but exits unexpectedly on a low-memory machine, reduce the scope by adding more paths to the exclude block, or increase the memory allocation for your Docker runtime.

If qodana report does not open a browser, check the terminal output for the local URL and port. You can copy that URL into a browser manually.

Limitations to keep in mind

Qodana's containerized model guarantees consistency, but it also means you cannot run it without a working container runtime. The resource cost of the first scan is real; plan accordingly on constrained hardware.

Finally, the qodana.yaml schema evolves. A configuration that works on one version of the CLI may warn or fail on another. Pin your CLI version in CI and locally, and validate the file against the documentation for that version before relying on it in a pipeline.