SonarScanner for Python

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

SonarScanner for Python — 1.3.0.4086 | Issue Tracker

1.3.0.4086 ^{_2025-12-02 Shai-Hulud security release} Download Release notes

---

1.2.1.3951 ^{_2025-10-31 Ensure compatibility with Python 3.14} Download Release notes

---

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-scanner is a wrapper around SonarScanner CLI, available on PyPI.

Prerequisites

• Python 3.8 or later

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. It assumes a Running SonarQube instance with a Python 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 sonar-project.properties file

• Through environment variables

Using 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 instance:

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.

[tool.sonar]
# must be unique in a given SonarQube 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.

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 instance:

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

Or:

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

Using 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 sonar-project.properties file

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

# must be unique in a given SonarQube 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 define configure the scanner through Environment variables:

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

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-scanner