# SonarScanner for Python
SonarScanner for Python — 1.4.0.4676 | Issue Tracker **1.4.0.4676** **2026-03-24**\ Added dry-run mode. Additional improvements, mostly regarding CI.\ [Download](https://pypi.org/project/pysonar/1.4.0.4676)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixversion%20%3D%201.4.0) *** **1.3.0.4086** **2025-12-02**\ Shai-Hulud security release\ [Download](https://pypi.org/project/pysonar/1.3.0.4086)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixversion%20%3D%201.3.0) *** **1.2.1.3951** **2025-10-31**\ Ensure compatibility with Python 3.14\ [Download](https://pypi.org/project/pysonar/1.2.1.3951)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixversion%20%3D%201.2.1) *** **1.1.0.2035** **2025-06-18**\ Improve handling of arguments and environment variables. Fix the return code on failure\ [Download](https://pypi.org/project/pysonar/1.1.0.2035/)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixVersion%20%3D%201.1) *** **1.0.2.1722** **2025-05-28**\ Fix incompatibility with tarfile.extractall\ [Download](https://pypi.org/project/pysonar/1.0.2.1722/)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixVersion%20%3D%201.0.2) *** **1.0.1.1548** **2025-04-02**\ Add support for sonar.organization property\ [Download](https://pypi.org/project/pysonar/1.0.1.1548/)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixVersion%20%3D%201.0.1) *** **1.0.0.1453** **2025-04-01**\ First production-ready release, includes support for automatic JRE provisioning\ [Download](https://pypi.org/project/pysonar/1.0.0.1453/)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixVersion%20%3D%201.0) *** **0.3.0.2016** **2025-06-17**\ Deprecate pysonar-scanner in favor of pysonar\ [Download](https://pypi.org/project/pysonar-scanner/0.3.0.2016/)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixVersion%20%3D%200.3) *** **0.2.0.520** **2024-10-15**\ Update embedded sonar-scanner-cli\ [Download](https://pypi.org/project/pysonar-scanner/0.2.0.520/)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixVersion%20%3D%200.2) *** **0.1.0.340** **2024-06-10**\ First beta release on PyPI\ [Download](https://pypi.org/project/pysonar-scanner/0.1.0.340/)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixVersion%20%3D%200.1.0.340) *** **0.1.0.285** **2024-04-08**\ First beta release on test.pypi.org\ [Download](https://test.pypi.org/project/pysonar/0.1.0.285/)\ \ [Release notes](https://sonarsource.atlassian.net/issues/?jql=project%20%3D%20%22Sonar%20Scanner%20Python%22%20AND%20fixVersion%20%3D%200.1.0.285)
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: ```css-79elbk 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](https://docs.sonarsource.com/sonarqube-server/2025.3/analyzing-source-code/scanners/sonarscanner "mention") directly. This means that analysis properties provided that way should be prepended with `-D`, for instance: ```css-79elbk 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: ```css-79elbk pysonar --token "MyToken" ``` See [CLI\_ARGS](https://github.com/SonarSource/sonar-scanner-python/blob/master/CLI_ARGS.md) for more details. **With a pyproject.toml file** Inside a `pyproject.toml`, Sonar analysis properties can be defined under the `tool.sonar` table. ```css-79elbk [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](https://docs.sonarsource.com/sonarqube-server/2025.3/analyzing-source-code/analysis-parameters "mention"). 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: ```css-79elbk [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: ```css-79elbk pysonar --toml-path "path/to/pyproject.toml" ``` Or: ```css-79elbk pysonar --sonar-project-base-dir "path/to/projectBaseDir" ``` Or: ```css-79elbk 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](https://docs.sonarsource.com/sonarqube-server/2025.3/analyzing-source-code/scanners/sonarscanner "mention"): ```css-79elbk # 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 [analysis-parameters](https://docs.sonarsource.com/sonarqube-server/2025.3/analyzing-source-code/analysis-parameters "mention"): ```css-79elbk 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: ```css-79elbk pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ pysonar ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sonarsource.com/sonarqube-server/2025.3/analyzing-source-code/scanners/sonarscanner-for-python.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.