Start FreeLog in
SonarCloud | Advanced setup | CI-based analysis | SonarScanner for Python (Beta)

Was this page helpful?

SonarScanner for Python (Beta)

On this page

pysonar-scanner is a wrapper around SonarScanner CLI, available on PyPI.


  • Python 3.8 or above

Installing the SonarScanner for Python

To install with pip, run the following command: 

pip install pysonar-scanner

Once installed, you can configure the analysis and run the scanner from the command line to perform an analysis. It assumes an existing SonarCloud project.

Using the SonarScanner for Python

Setting the analysis properties

For the analysis to run, you'll need to define analysis properties. There are multiple ways of providing them, described below in descending order of priority:

  • Through CLI arguments to the pysonar-scanner command
  • Under the [tool.sonar] key of the pyproject.toml file
  • Through common properties extracted from the pyproject.toml file
  • In a dedicated file
  • Through environment variables

Through CLI arguments

Analysis properties can be provided as CLI arguments to the pysonar-scanner command. They follow the same convention as when running the SonarScanner CLI directly. This means that analysis properties provided that way should be prepended with -D, for example:

pysonar-scanner -Dsonar.token=myAuthenticationToken 

You can use all the arguments allowed by the SonarScanner CLI.

With a pyproject.toml file

Inside a pyproject.toml, Sonar analysis properties can be defined under the tool.sonar table.

# must be unique in a given SonarCloud instance

# --- optional properties ---
# defaults to project key
#projectName=My project
# defaults to 'not provided'
# Path is relative to the pyproject.toml file. Defaults to .
# Encoding of the source code. Default is default system encoding

For a list of analysis parameters, see Analysis parameters.

In the pyproject.toml file, the prefix sonar. for parameter keys should be omitted. For example, sonar.scm.provider in the documentation will become scm.provider in the pyproject.toml file.

By default, the scanner expects the pyproject.toml file to be present in the current directory. However, its path can be provided manually through the toml.path (PYSCAN-40) CLI argument as well as through the sonar.projectHome argument. For example:

pysonar-scanner -Dtoml.path="path/to/pyproject.toml"


pysonar-scanner -Dsonar.projectHome="path/to/projectHome"

Through project properties extracted from the pyproject.toml file

When a pyproject.toml file is available, it's possible to set the -read-project-config flag to allow the scanner to deduce analysis properties from the project configuration.

This is currently supported only for projects using poetry.

The Sonar scanner will then use the project name and version defined through Poetry, they won't have to be duplicated under a dedicated tool.sonar section.

With a file

The analysis can be configured with a file, exactly like when you analyze with SonarScanner CLI:

# must be unique in a given SonarCloud instance

# --- optional properties ---

# defaults to project key
#sonar.projectName=My project
# defaults to 'not provided'
# Path is relative to the file. Defaults to .
# Encoding of the source code. Default is default system encoding

Through environment variables

You can use environment variables on the CI/CD host to define analysis parameters. See Analysis parameters to see which parameters can be set through environment variables. For example:

export SONAR_HOST_URL="http://localhost:9000"

Installing from testPyPI

To install the latest pre-released version of SonarScanner for Python. Execute the following command:

pip install --index-url --extra-index-url pysonar-scanner

© 2008-2024 SonarSource SA. All rights reserved. SONAR, SONARSOURCE, SONARLINT, SONARQUBE, SONARCLOUD, and CLEAN AS YOU CODE are trademarks of SonarSource SA.

Creative Commons License