Qodana 2025.2 Help

Python

All Qodana linters are based on JetBrains IDEs designed for particular programming languages and frameworks. To analyze Python projects, you can use the following linters:

Characteristic

Description

Linter name

qodana-python

Docker image

jetbrains/qodana-python:2025.2

Based on

PyCharm Professional

Available under licenses

Ultimate and Ultimate Plus licenses

Shipped as

A native solution and a Docker image

Supported languages

Python, JavaScript and TypeScript

Characteristic

Description

Linter name

qodana-python-community

Docker image

jetbrains/qodana-python-community:2025.2

Based on

PyCharm Community Edition

Available under licenses

Community license

Shipped as

A Docker image

Supported languages

Python

To see the list of supported technologies and features, you can navigate to the Supported technologies and features chapter of this section.

Before you start

Install dependencies

If your project has external pip dependencies, set them up using the bootstrap key in the qodana.yaml file. For example, if your project dependencies are specified by the requirements.txt file in your project root, go into the configuration file and add the following line:

bootstrap: pip install -r requirements.txt

Qodana Cloud

Depending on the specific linter you're using, you may need to get a project token that will be used by Qodana for identifying and verifying a license. To do this, follow these steps:

  1. Navigate to Qodana Cloud and create an account there.

  2. In Qodana Cloud, create an organization, a team, and a project.

  3. On the project card, you can find the project token that you will be using further in this section.

Prepare your software

On the Settings tab of the GitHub UI, create the QODANA_TOKEN encrypted secret and save the project token as its value.

  1. In Jenkins, make sure that these plugins are up and running:

    Make sure that Docker is installed and accessible to Jenkins.

    If applicable, make sure that Docker is accessible to the jenkins user as described in the Manage Docker as a non-root user section of the Docker documentation.

  2. In Jenkins, create the qodana-token credential and save the project token as its value.

  3. In Jenkins, create a Multibranch Pipeline project as described on the Jenkins documentation portal.

  1. Make sure that your project repository is accessible to GitLab CI/CD.

  2. In GitLab CI/CD, create the QODANA_TOKEN variable and save the project token as its value.

In TeamCity, Create a project and a build configuration.

Install Docker on the machine you are going to run Qodana.

If you are using Linux, you should be able to run Docker under your current non-root user.

Follow the instructions from the Qodana CLI page on GitHub.

Run the command to pull the Docker image of the Qodana for Python or Qodana Community for Python linter:

docker pull jetbrains/qodana-python<-community>:2025.2-eap

Run Qodana

You can run Qodana linters using the following methods:

  • Native mode as the recommended method for running linters without Docker

  • Container mode using Docker containers of Qodana

  • PyCharm

You can run Qodana using the Qodana Scan GitHub action.

To analyze the main branch, release branches and the pull requests coming to your repository in native mode, save this workflow configuration to the .github/workflows/code_quality.yml file:

name: Qodana on: workflow_dispatch: pull_request: push: branches: # Specify your branches here - main # The 'main' branch - 'releases/*' # The release branches jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2025.2 with: args: | --linter,qodana-python<-community>, --within-docker,false env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

This configuration uses the --linter option to specify a linter. The --within-docker option in the false state is used for enabling native mode.

More configuration examples are available in the GitHub Actions section.

Run this command in the project root directory:

qodana scan \    -e QODANA_TOKEN="<qodana-cloud-token>" \    --linter qodana-python<-community> \    --within-docker false

This configuration uses the --linter option to specify a linter. The --within-docker option in the false state is used for enabling native mode.

If you are using another Qodana Cloud instance than https://qodana.cloud/, override it by declaring the QODANA_ENDPOINT environment variable.

In your browser, open Qodana Cloud to examine the analysis results and reconfigure the analysis. See the Analysis reports section of the documentation for full details.

Container mode is available for all linters; however, it is advised that you use native mode whenever possible.

To analyze the main branch, release branches and the pull requests coming to your repository in container mode, save this workflow configuration to the .github/workflows/code_quality.yml file:

name: Qodana on: workflow_dispatch: pull_request: push: branches: # Specify your branches here - main # The 'main' branch - 'releases/*' # The release branches jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2025.2 with: # Uncomment the linter that you wish to use # args: --linter,qodana-python # args: --linter,qodana-python-community env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

More configuration examples are available in the GitHub Actions section.

Save this configuration to the Jenkinsfile:

pipeline { environment { QODANA_TOKEN=credentials('qodana-token') } agent { docker { args ''' -v "${WORKSPACE}":/data/project --entrypoint="" ''' // Uncomment the image that you would like to employ // image 'jetbrains/qodana-python:2025.2' // Qodana for Python // image 'jetbrains/qodana-python-community:2025.2' //Qodana Community for Python } } stages { stage('Qodana') { steps { sh '''qodana''' } } } }

More configuration examples are available in the Jenkins section.

In the root directory of your project, save this snippet to the .gitlab-ci.yml file:

include: - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2025.2 inputs: # Uncomment the image that you would like to employ # args: --linter,qodana-python # Qodana for Python # args: --linter,qodana-python-community # Qodana Community for Python

More configuration examples are available in the GitLab CI/CD section.

  1. In the TeamCity UI, navigate to the configuration page of a build where you would like to run Qodana.

  2. On the Build Configuration Settings page, navigate to the Build steps page.

  3. On the Build steps page, click the Add build step button.

  4. On the page that opens, select the Qodana runner.

  5. On the New Build Step: Qodana page, click Show advanced options and configure the Qodana runner:

    • Step name uniquely identifies this step among other build steps.

    • Step ID uniquely identifies this step among other build steps.

    • Execute step configures the build condition that will trigger this build step.

    • Working directory sets the directory for the build process, see the TeamCity documentation for details. You can leave this field empty if the Checkout directory parameter is specified on the Version Control Settings tab.

    • Report ID uniquely identifies the report to let you distinguish between multiple reports when several analysis steps are configured within a single build.

    • The Forward reports to TeamCity tests checkbox configures Qodana report availability in the Test tab of the TeamCity UI. Using this option, you can view codebase problems along with other problems detected.

    • Linter configures the Qodana linter.

      Here, select the Qodana for Python linter.

    • Version is by default set to Latest.

    • Inspection profile defines an inspection profile:

    • Cloud Token configures a project token generated in Qodana Cloud.

    • Additional Docker arguments configure the arguments accepted by a Docker image, see the Configuration options section for details.

    • Additional Qodana arguments let you extend the default Qodana functionality, see the Types of options section for details.

    • Qodana CLI version lets you specify the Qodana CLI version that you would like to use.

    Configuring the Qodana runner

  6. Click the Save button.

More configuration examples are available in the TeamCity section.

qodana scan \    -e QODANA_TOKEN="<qodana-cloud-token>" \ # Uncomment the image that you would like to employ # --linter qodana-python # Qodana for Python # --linter qodana-python-community # Qodana Community for Python
docker run \    -v <source-directory>/:/data/project/ \    -e QODANA_TOKEN="<cloud-project-token>" \ # Uncomment the image that you would like to employ # jetbrains/qodana-python:2025.2 # Qodana for Python # jetbrains/qodana-python-community:2025.2 # Qodana Community for Python

If you are using another Qodana Cloud instance than https://qodana.cloud/, override it by declaring the QODANA_ENDPOINT environment variable.

In your browser, open Qodana Cloud to examine the analysis results and reconfigure the analysis. See the Analysis reports section of the documentation for full details.

  1. In PyCharm, navigate to Tools | Qodana | Try Code Analysis with Qodana.

  2. On the Run Qodana dialog, you can configure Qodana.

    Configuring Qodana in the Run Qodana dialog

    This dialog contains the following components:

    Name

    Description

    The qodana.yaml file

    In the text field, you can set up code analysis used by Qodana in this file. You can learn more about available configuration options

    The Send analysis results to Qodana Cloud option

    If you want to send reports to Qodana Cloud, you can check this option and paste the project token generated in Qodana Cloud

    The Save qodana.yaml in project root option

    By checking this option, you can save the Qodana configuration made on this dialog to the qodana.yaml file in the project root of your project

    The Use Qodana analysis baseline option

    Using the baseline feature, you can skip analysis for specific problems

    Click Run for analyzing your code.

  3. On the Server-Side Analysis tab of the Problems tool window, see the analysis results.

Explore analysis results

You can load the latest Qodana report from Qodana Cloud to PyCharm as explained below.

  1. In PyCharm, navigate to Tools | Qodana | Log in to Qodana.

  2. On the Settings dialog, click Log in.

    Connecting to Qodana Cloud

    This will redirect you to the authentication page.

  3. Select the Qodana Cloud project to link your local project with.

    Linking the project to Qodana Cloud

  4. If you check the Always load most relevant Qodana report option, you will be able to receive the most actual and relevant reports from Qodana Cloud.

    Enabling to load the most relevant reports

    In this case, the IDE will search Qodana Cloud and fetch the report with the revision ID corresponding to the current revision ID (HEAD). If this report is not found, the IDE will select the previous report with the revision ID closest to the current revision ID (HEAD). Otherwise, the IDE retrieves the latest available report from Qodana Cloud.

  5. On the Server-Side Analysis tab of the Problems tool window, you can view the analysis results.

After Qodana analyzed your project and uploaded the analysis results to Qodana Cloud, in Qodana Cloud navigate to your project and review the analysis results report.

Analysis report example

To learn more about Qodana report UI, see the Analysis reports section.

Extend Qodana configuration

Adjusting the scope of analysis

Out of the box, Qodana provides two predefined profiles hosted on GitHub:

  • qodana.starter is the default profile and a subset of the more comprehensive qodana.recommended profile.

  • qodana.recommended is suitable for running in CI/CD pipelines and mostly implements the default PyCharm profile; see the PyCharm documentation for details.

You can customize Qodana profiles using configurations in YAML and XML formats. To learn more about configuration basics, visit the Configure Qodana your way section of the documentation.

Enabling the baseline feature

You can skip analysis for specific problems by using the baseline feature. Information about a baseline is contained in a SARIF-formatted file.

Save this snippet to the .github/workflows/code_quality.yml file containing the args: --baseline,qodana.sarif.json option that specifies the path to the SARIF-formatted baseline file:

name: Qodana on: workflow_dispatch: pull_request: push: branches: # Specify your branches here - main # The 'main' branch - master # The 'master' branch - 'releases/*' # The release branches jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2025.2 with: # Uncomment the linter that you wish to use # args: --baseline,<path/to/qodana.sarif.json>,--linter,qodana-python # args: --baseline,<path/to/qodana.sarif.json>,--linter,qodana-python-community env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

In the Jenkinsfile, save the configuration containing the --baseline <path/to/qodana.sarif.json> line that specifies the path to the SARIF-formatted baseline file:

pipeline { environment { QODANA_TOKEN=credentials('qodana-token') } agent { docker { args ''' -v "${WORKSPACE}":/data/project --entrypoint="" ''' // Uncomment the linter you would like to employ // image 'jetbrains/qodana-python:2025.2' // Qodana for Python // image 'jetbrains/qodana-python-community:2025.2' // Qodana Community for Python } } stages { stage('Qodana') { steps { sh ''' qodana \ --baseline <path/to/qodana.sarif.json> ''' } } } }

In the root directory of your project, save this snippet to the .gitlab-ci.yml file:

include: - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2025.2 inputs: # Uncomment the linter you would like to employ # args: --linter,qodana-python # Qodana for Python # args: --linter,qodana-python-community # Qodana Community for Python

The --baseline <path/to/qodana.sarif.json> line in the script block invokes the baseline feature.

  1. In the TeamCity UI, navigate to the configuration page of a build where you would like to run Qodana.

  2. On the Build Configuration Settings page, navigate to the Build steps page.

  3. On the Build steps page, click the Add build step button.

  4. On the page that opens, select the Qodana runner.

  5. On the New Build Step: Qodana page, click Show advanced options and configure the Qodana runner:

    • Step name uniquely identifies this step among other build steps.

    • Step ID uniquely identifies this step among other build steps.

    • Execute step configures the build condition that will trigger this build step.

    • Working directory sets the directory for the build process, see the TeamCity documentation for details. You can leave this field empty if the Checkout directory parameter is specified on the Version Control Settings tab.

    • Report ID uniquely identifies the report to let you distinguish between multiple reports when several analysis steps are configured within a single build.

    • The Forward reports to TeamCity tests checkbox configures Qodana report availability in the Test tab of the TeamCity UI. Using this option, you can view codebase problems along with other problems detected.

    • Linter configures the Qodana linter.

      Here, select the Qodana for Python linter.

    • Version is by default set to Latest.

    • Inspection profile defines an inspection profile:

    • Cloud Token configures a project token generated in Qodana Cloud.

    • Additional Docker arguments configure the arguments accepted by a Docker image, see the Configuration options section for details.

    • Additional Qodana arguments let you extend the default Qodana functionality, see the Types of options section for details.

      In this field, specify the baseline feature using the --baseline <path/to/qodana.sarif.json> option.

    • Qodana CLI version lets you specify the Qodana CLI version that you would like to use.

    Configuring the Qodana runner

  6. Click the Save button.

Choose how you would like to run the baseline feature from the command line:

qodana scan \     -v <path_to_baseline>:/data/base/ \     -e QODANA_TOKEN="<cloud-project-token>" \     # Uncomment the linter you would like to employ     # --image qodana-python \ # Qodana for Python     # --image qodana-python-community \ # Qodana Community for Python     --baseline /data/base/<path-relative-to-project-dir>/qodana.sarif.json
docker run \     -v <source-directory>/:/data/project/ \     -v <path_to_baseline>:/data/base/ \     -e QODANA_TOKEN="<cloud-project-token>" \     # Uncomment the linter you would like to employ     # jetbrains/qodana-python:2025.2 \ # Qodana for Python     # jetbrains/qodana-python-community:2025.2 \ # Qodana Community for Python     --baseline /data/base/<path-relative-to-project-dir>/qodana.sarif.json

  1. In PyCharm, navigate to the Problems tool window.

  2. In the Problems tool window, click the Server-Side Analysis tab.

  3. On the Server-Side Analysis tab, click the Try Locally button.

  4. On the dialog that opens, expand the Advanced configuration section and specify the path to the baseline file, and then click Run.

Enabling the quality gate

You can configure quality gates for the total number of project problems, specific problem severities, and code coverage by saving this snippet to the qodana.yaml file:

failureConditions:   severityThresholds:     any: 50 # Total number of problems in all severities     critical: 1 # Severities     high: 2     moderate: 3     low: 4     info: 5   testCoverageThresholds:     fresh: 6 # Fresh code coverage     total: 7 # Total percentage

You can configure quality gates for the total number of project problems and specific problem severities by saving this snippet to the qodana.yaml file:

failureConditions:   severityThresholds:     any: 50 # Total number of problems in all severities     critical: 1 # Severities     high: 2     moderate: 3     low: 4     info: 5

Analyzing pull requests

The Qodana Scan GitHub action automatically analyzes all pull requests, so you do not have to provide any additional configuration. Save this configuration to the .github/workflows/code_quality.yml file:

name: Qodana on: workflow_dispatch: pull_request: push: branches: # Specify your branches here - main # The 'main' branch - 'releases/*' # The release branches jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2025.2 with: args: | --linter,qodana-python<-community>, --within-docker,false env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

To analyze changes in your code, employ the --diff-start option and specify a hash of the commit that will act as a base for comparison:

qodana scan \    -e QODANA_TOKEN="<qodana-cloud-token>" \    --linter qodana-python<-community> \    --within-docker false \    --diff-start=<GIT_START_HASH>

In your browser, open Qodana Cloud to examine the analysis results and reconfigure the analysis. See the Analysis reports section of the documentation for full details.

The Qodana Scan GitHub action automatically analyzes all pull requests, so you do not have to provide any additional configuration. Save this configuration to the .github/workflows/code_quality.yml file:

name: Qodana on: workflow_dispatch: pull_request: push: branches: # Specify your branches here - main # The 'main' branch - 'releases/*' # The release branches jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2025.2 with: # Uncomment the Docker image that you wish to use # args: --image,qodana-python # Qodana for Python # args: --image,qodana-python-community # Qodana Community for Python env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

In the root directory of your project, save the .gitlab-ci.yml file containing the following snippet:

include: - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2025.2 inputs: # Uncomment the Docker image that you wish to use # args: --image,qodana-python # Qodana for Python # args: --image,qodana-python-community # Qodana Community for Python

This configuration enables merge request analysis.

Information about configuring TeamCity for analyzing pull and merge requests is available on the TeamCity documentation portal.

To analyze changes in your code, employ the --diff-start option and specify a hash of the commit that will act as a base for comparison:

qodana scan \    -e QODANA_TOKEN="<cloud-project-token>" \     # Uncomment the Docker image that you wish to use     # --image qodana-python \ # Qodana for Python     # --image qodana-python-community \ # Qodana Community for Python    --diff-start=<GIT_START_HASH>
docker run \    -v $(pwd):/data/project/ \    -e QODANA_TOKEN="<cloud-project-token>" \     # Uncomment the Docker image that you wish to use     # jetbrains/qodana-python:2025.2 \ # Qodana for Python     # jetbrains/qodana-python-community:2025.2 \ # Qodana Community for Python    --diff-start=<GIT_START_HASH>

Overriding the Python interpreter

You can tell the qodana-python and qodana-python-community linters to use a different version of the Python interpreter. To do this, follow the instructions below.

  1. In the bootstrap section of the qodana.yaml file, save the following snippet:

    # Create `qodana-env` environment with specific Python version bootstrap: | . ~/.bashrc conda create -y -n qodana-env python=2.7 # Python version conda activate qodana-env # Activate the created environment

  2. Use the QODANA_PYTHON_PATH variable to pass the path to the Python binary containing the environment, for example:

    -e QODANA_PYTHON_PATH:/data/cache/conda/envs/qodana-env/bin/python

    Examples of using variables are provided in the Run Qodana section.

Supported technologies and features

This table contains the list of technologies and Qodana features supported by both linters.

Support for

Name

Qodana for Python

Qodana Community for Python

Programming languages

Python

JavaScript and TypeScript

✔

✔

✔

 

Frameworks and libraries

Pandas

Pyramid

Node.js

React

Vue

✔

✔

✔

✔

✔

✔

 

 

 

 

Databases and ORM

MySQL

MongoDB

Oracle

SQL

SQL Server

PostgreSQL

✔

✔

✔

✔

✔

✔

 

 

 

 

 

 

Markup languages

HTML

JSON and JSON5

RELAX NG

XML

YAML

TOML

SASS/SCSS

PostCSS

Less

CSS

JSONPath

✔

✔

✔

✔

✔

✔

✔

✔

✔

✔

✔

✔

✔

✔

✔

✔

✔

 

 

 

 

 

Scripting languages

Shell script

✔

✔

Other

Regular expressions

Structural search

HTTP Client

✔

✔

✔

✔

 

 

Qodana features

Baseline

Quality gate

Code coverage

FlexInspect

Insights*

License audit*

Quick-Fix

Single Sign-on*

Vulnerability checker*

✔

✔

✔

✔

✔

✔

✔

✔

✔

✔

✔

 

 

 

 

* Available only under the Ultimate Plus license.

03 December 2025
Overview of linters.NET