SonarScanner for Python
1.0.1.1548 2025-04-02
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 thepyproject.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 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="https://sonarcloud.io"
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
Was this page helpful?