SonarScanner for Python

The SonarScanner for Python provides an easy way to start the analysis of a Python project with SonarQube Server.

SonarScanner for Python — 1.1.0.2035 | Issue Tracker

1.1.0.2035 ^{_2025-06-18 Improve handling of arguments and environment variables. Fix the return code on failure} Download Release notes

1.0.2.1722 ^{_2025-05-28 Fix incompatibility with tarfile.extractall} Download Release notes

1.0.1.1548 ^{_2025-04-02 Add support for sonar.organization property} Download Release notes

1.0.0.1453 ^{_2025-04-01 First production-ready release, includes support for automatic JRE provisioning} Download Release notes

0.3.0.2016 ^{_2025-06-17 Deprecate pysonar-scanner in favor of pysonar} Download Release notes

0.2.0.520 ^{_2024-10-15 Update embedded sonar-scanner-cli} Download Release notes

0.1.0.340 ^{_2024-06-10 First beta release on PyPI} Download Release notes

0.1.0.285 ^{_2024-04-08 First beta release on test.pypi.org} Download Release notes

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

Prerequisites

• Python 3.9 or later

Installing the SonarScanner for Python

To install with pip, run the following command:

pip install pysonar

Using the SonarScanner for Python

Once installed, you can configure the analysis and run the scanner from the command line. It assumes a running instance of SonarQube Server or a project configured on SonarQube Cloud.

We do not recommend running an antivirus scanner on the machine where a SonarQube Server analysis runs, it could result in unpredictable behavior.

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 command

• Environment variables for individual properties (e.g. SONAR_TOKEN, SONAR_VERBOSE, SONAR_HOST_URL, …)

• Generic environment variable SONAR_SCANNER_JSON_PARAMS

• Under the [tool.sonar] key of the pyproject.toml file

• In a dedicated sonar-project.properties file

• Through common properties extracted from the pyproject.toml

Using CLI arguments

Analysis properties can be provided as CLI arguments to the pysonar 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 instance:

pysonar -Dsonar.token=myAuthenticationToken

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

Additionally, some common properties can be provided using a shorter alias, such as:

pysonar --token "MyToken"

See CLI_ARGS for more details.

With a pyproject.toml file

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

[tool.sonar]

# must be unique in a given SonarQube Server/SonarQube Cloud instance

projectKey=my:project

# --- optional properties ---

# defaults to project key

#projectName=My project

# defaults to 'not provided'

#projectVersion=1.0



# Path is relative to the pyproject.toml file. Defaults to .

#sources=.



# Encoding of the source code. Default is default system encoding

#sourceEncoding=UTF-8

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.

Properties in pyproject.toml files are expected to be provided in camel case. However, kebab case is also accepted:

[tool.sonar]

project-key=My Project key # valid alias for projectKey

By default, the scanner will expect the pyproject.toml file to be present in the current directory. However, its path can be provided manually through the toml-path CLI argument as well as through the sonar.projectBaseDir argument. For instance:

pysonar --toml-path "path/to/pyproject.toml"

Or:

pysonar --sonar-project-base-dir "path/to/projectBaseDir"

Or:

pysonar -Dsonar.projectBaseDir="path/to/projectBaseDir"

Using project properties extracted from the pyproject.toml file

When a pyproject.toml file is available, the scanner can deduce analysis properties from the project configuration. This is currently supported only for projects using poetry.

With a sonar-project.properties file

The analysis can be configured with a sonar-project.properties file, exactly like when you analyze with the SonarScanner CLI.

# must be unique in a given SonarQube Server/SonarQube Cloud instance

sonar.projectKey=my:project

# --- optional properties ---

# defaults to project key

#sonar.projectName=My project

# defaults to 'not provided'

#sonar.projectVersion=1.0



# Path is relative to the sonar-project.properties file. Defaults to .

#sonar.sources=.



# Encoding of the source code. Default is default system encoding

#sonar.sourceEncoding=UTF-8

Through environment variables

It is also possible to configure the scanner through environment variables:

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

Installing from testPyPI

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

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ pysonar