SonarScanner CLI
The SonarScanner CLI analyzes code in CI/CD when no build-specific scanner exists. Distinct from the SonarQube CLI, a developer management interface. This page is for SonarQube Server 2025.2.
The SonarScanner CLI is the scanner to use when there is no specific scanner for your build system. It supports ARM architecture for macOS and Linux.
Important: The SonarScanner CLI doesn't support C# or VB.NET analysis. To analyze C# or VB.NET projects, use the Introduction instead.
SonarScanner CLI vs. SonarQube CLI
This page documents the SonarScanner CLI: a code analysis scanner for CI/CD pipelines, invoked with the sonar-scanner command.
It's a distinct product from the SonarQube CLI, a command-line interface for interacting with Sonar products, including viewing projects and issues, analyzing files, scanning for secrets, and configuring AI agent integrations.
Prerequisites
Java 17 or later
With JRE auto-provisioning:
Java 11 or later from SonarScanner CLI version 7.2
Java 17 or later before SonarScanner CLI version 7.2
See General requirements for more information.
Configuring your project
Create a configuration file in your project’s root directory called sonar-project.properties.
Running SonarScanner CLI from the zip file
To run SonarScanner CLI from the zip file, follow these steps:
Expand the downloaded file into the directory of your choice. We’ll refer to it as
<INSTALL_DIRECTORY>in the next steps.Update the global settings to point to your SonarQube Server instance:
Open the
$<INSTALL_DIRECTORY>/conf/sonar-scanner.propertiesfile.Uncomment and edit the
#sonar.host.url=http://localhost:9000line to point to your SonarQube Server’s URL.
Add the
<INSTALL_DIRECTORY>/bindirectory to your path.Verify your installation by opening a new shell and executing the command
sonar-scanner -h. You should get an output like this:usage: sonar-scanner [options]Options:-D,--define <arg> Define property-h,--help Display help information-v,--version Display version information-X,--debug Produce execution debug outputIf you need more debug information, you can add one of the following to your command line:
-X,--verbose, or-Dsonar.verbose=true.Run the following command from the project base directory to launch analysis and pass your Managing your tokens:
sonar-scanner -Dsonar.token=myAuthenticationTokenAlternatively, instead of passing the token in your command line, you can create the
SONAR_TOKENenvironment variable and set the token as its value before you launch the analysis.
Expand the downloaded file into the directory of your choice. We’ll refer to it as
<INSTALL_DIRECTORY>in the next steps.Update the global settings to point to your SonarQube Server instance:
Open the
$<INSTALL_DIRECTORY>\conf\sonar-scanner.propertiesfile.Uncomment and edit the
#sonar.host.url=http://localhost:9000line to point to your SonarQube Server instance’s URL.
Add the
<INSTALL_DIRECTORY>\bindirectory to your path.Verify your installation by opening a new shell and executing the command
sonar-scanner.bat -h. You should get an output like this:usage: sonar-scanner [options]Options:-D,--define <arg> Define property-h,--help Display help information-v,--version Display version information-X,--debug Produce execution debug outputIf you need more debug information, you can add one of the following to your command line:
-X,--verbose, or-Dsonar.verbose=true.Run the following command from the project base directory to launch analysis and pass your Managing your tokens:
sonar-scanner -Dsonar.token=myAuthenticationTokenAlternatively, instead of passing the token in your command line, you can create the
SONAR_TOKENenvironment variable and set the token as its value before you launch the analysis.
Running SonarScanner CLI from the Docker image
To scan using the SonarScanner CLI Docker image, use the following command:
Use a sonar-project.properties file to configure other analysis parameters: see Configuring your project above.
Scanning C, C++, or Objective-C projects
Scanning projects that contain C, C++, or Objective-C code requires some additional analysis steps. You can find full details on the C/C++/Objective-C analysis overview language page.
Sample projects
To help you get started, simple project samples are available for most languages on GitHub. They can be browsed or downloaded. You’ll find them filed under sonarqube-scanner/src.
Alternatives to sonar-project.properties
If a sonar-project.properties file cannot be created in the root directory of the project, there are several alternatives:
The properties can be specified directly through the command line. Example:
sonar-scanner -Dsonar.projectKey=myproject -Dsonar.sources=src1The property
project.settingscan be used to specify the path to the project configuration file (this option is incompatible with thesonar.projectBaseDirproperty). Example:sonar-scanner -Dproject.settings=../myproject.propertiesThe root folder of the project to analyze can be set through the
sonar.projectBaseDirproperty since SonarScanner CLI 2.4. This folder must contain asonar-project.propertiesfile ifsonar.projectKeyis not specified on the command line. Additional analysis parameters can be defined in this project configuration file or through command-line parameters.
Alternate analysis directory
If the files to be analyzed are not in the directory where the analysis starts from, use the sonar.projectBaseDir property to move analysis to a different directory. E.g. analysis begins from jenkins/jobs/myjob/workspace but the files to be analyzed are in ftpdrop/cobol/project1. This is configured in sonar-project.properties as follows:
Advanced configuration
If your SonarQube Server instance is secured
If your SonarQube Server instance is Securing SonarQube Server behind a proxy and a self-signed certificate, you must add the self-signed certificate to the trusted CA certificates of the SonarScanner. In addition, if mutual TLS is used, you must define the access to the client certificate at the SonarScanner level.
Troubleshooting
Java heap space error or java.lang.OutOfMemoryError
Increase the memory using SONAR_SCANNER_JAVA_OPTS environment variable for SonarScanner CLI version 6.0 and higher. For the previous versions use SONAR_SCANNER_OPTS:
In Windows environments, avoid the double quotes, since they get misinterpreted, and combine the two parameters into a single one.
"java" cannot be opened because the developer cannot be verified
The SonarScanner CLI is not yet Apple verified therefore, when using the macOS AArch64 version, you may get an OS security window displaying this message. A solution us to run:
Unsupported major.minor version
Install the last version of SonarScanner CLI (from version 6.0, no JRE installation is required). Otherwise, upgrade the version of Java being used for analysis or use one of the native package (that embed its own Java runtime).
Property missing: ‘sonar.cs.analyzer.projectOutPaths’. No protobuf files will be loaded for this project.
The SonarScanner CLI is not able to analyze .NET projects. Please, use the Introduction. If you are running the SonarScanner for .NET, ensure that you are not hitting a known limitation.
Last updated
Was this helpful?