A modernized navigation and workspace experience is now available in SonarQube Community Build.
See the release notes
Ctrlk
Start Free
For the complete documentation index, see llms.txt. This page is also available as Markdown.

SonarScanner for Cargo

The SonarScanner for Cargo provides an easy way to start the analysis of a Rust project with SonarQube Community Build.

1.0.0 2026-09-11

  • First generally available release. Runs an analysis with cargo sonar-scanner, configured from the [package.metadata.sonar] table in Cargo.toml.

Download Release notes

The SonarScanner for Cargo is the scanner to use for Rust projects built with Cargo. It runs as a Cargo subcommand: an analysis is a single cargo sonar-scanner call that reads its configuration from your Cargo.toml.

Prerequisites

  • Cargo, the Rust package manager. Install it from rustup.rs.

  • Clippy, the Rust linter that the Rust analyzer runs by default on SonarQube Community Build. Install it with rustup component add clippy.

  • See General requirements for more details.

See Rust for what the Rust analyzer supports.

Installation

To install the scanner, run:

cargo install cargo-sonar-scanner

To download a prebuilt binary instead of compiling from source, use cargo binstall:

cargo binstall cargo-sonar-scanner

The binary is called cargo-sonar-scanner. Once it is on your PATH, Cargo resolves cargo sonar-scanner. Verify your installation by running:

cargo sonar-scanner --help

Use

  • Add a [package.metadata.sonar] table to the Cargo.toml in the root directory of the project. Cargo reserves this table for third-party tools and otherwise ignores it, making it the recommended place to identify your project and define the server connection.

Do not put your token in Cargo.toml. The file is committed, and for a library crate it is published inside the .crate archive on crates.io, where it cannot be deleted. The scanner warns if it finds one. Use SONAR_TOKEN instead.

  • Set the environment variable SONAR_TOKEN with a user token. Note that the token can also be set through the command line argument -Dsonar.token.

  • Run the command cargo sonar-scanner from the project base directory to run the analysis.

sonar.host.url is required. With nothing set, the scanner resolves to SonarQube Cloud and your server token is rejected there: a missing host URL surfaces as an authentication failure against an unexpected host. Check the endpoint that --dry-run reports before chasing the token.

Property key naming

Bare keys are written in kebab-case and get a sonar. prefix; nested tables become dotted segments:

You write
It becomes

project-key = "x"

sonar.projectKey=x

exclusions = ["a/**", "b/**"]

sonar.exclusions=a/**,b/**

verbose = true

sonar.verbose=true

connect-timeout = 30 under [package.metadata.sonar.scanner]

sonar.scanner.connectTimeout=30

host-url = "…"

sonar.host.url=… (the one alias)

"sonar.cpd.exclusions" = "…"

sonar.cpd.exclusions=… (verbatim)

Every analysis parameter is accepted, because the name is derived rather than looked up in a list. The exception is sonar.host.url, whose real name is dotted where the convention would produce sonar.hostUrl. It has an alias instead. Anything the convention cannot express can be written as a quoted, fully qualified parameter name.

For a list of analysis parameters, see Parameters not settable in the UI.

Analysis scope

Cargo build output is not excluded from the analysis for you. Exclude it explicitly, otherwise target/ is indexed along with your sources:

Adjust the pattern if CARGO_TARGET_DIR points the build output somewhere else.

Workspaces

The scanner analyzes the project in the base directory, which defaults to the directory you run it from. It does not walk up to a workspace root: running it from inside a member crate analyzes that member, configured by that member's own Cargo.toml.

In a virtual workspace (a root Cargo.toml with no [package] section), use [workspace.metadata.sonar] instead. When one manifest carries both tables, [package.metadata.sonar] wins key by key.

To analyze a directory other than the one you run from, set sonar.projectBaseDir.

Alternatives to the Cargo.toml table

If the analysis cannot be configured in Cargo.toml, the alternatives are:

  • A sonar-project.properties file in the base directory, exactly like when you analyze with the SonarScanner CLI. This is supported to keep a project migrating from the SonarScanner CLI working.

  • Parameters specified directly on the command line, prefixed with -D. Example:

  • Environment variables. Named parameters such as sonar.token use SONAR_TOKEN and sonar.host.url uses SONAR_HOST_URL; any sonar.scanner.* parameter maps to SONAR_SCANNER_*: sonar.scanner.connectTimeout becomes SONAR_SCANNER_CONNECT_TIMEOUT.

In all cases, sonar.projectKey is mandatory and must be defined either in Cargo.toml, in the project configuration file, or on the command line.

When the same parameter is set in more than one place, the command line wins, then environment variables, then Cargo.toml, then sonar-project.properties. Run cargo sonar-scanner --dry-run to print the origin of every resolved parameter, which is the quickest way to answer "where did that value come from?".

For more information, see Configuration overview.

Custom certificates

Behind a TLS-intercepting proxy, or against a server with a private certificate authority, point the scanner at a PKCS#12 truststore:

Trust is widened, not replaced: a truststore holding only your corporate root does not cut off anything else. If the server asks for a client certificate, supply a keystore holding the private key and its chain with sonar.scanner.keystorePath and sonar.scanner.keystorePassword.

A truststore at the default path <sonar.userHome>/ssl/truststore.p12 is read whether or not you set the parameter. Dropping a truststore.p12 into ~/.sonar/ssl is enough on its own. The default password is changeit, then sonar. The same parameters reach the analysis itself: one truststore covers the whole run. See TLS certificates on client side for more details.

Troubleshooting

Checking the resolved configuration

Start by separating configuration from connectivity. The following command resolves the configuration and makes no network request:

It prints the endpoint, base directory, every resolved parameter, and the origin of each one. Sensitive values are masked. Add --verbose to also show the loaded files in the log.

Authentication failures

For a rejected token (HTTP 401), generate or select a token for the target shown by --dry-run, then set SONAR_TOKEN again. A 403 means the token was accepted but cannot run the analysis; check its analysis permissions and the project parameters.

Connection failures

Check the resolved host URL with --dry-run first. A certificate error behind a corporate TLS-inspecting proxy is a truststore problem: configure one as described in #custom-certificates, rather than disabling certificate verification. Standard proxy environment variables are used unless scanner proxy parameters override them:

sonar.scanner.proxyUser and sonar.scanner.proxyPassword configure proxy credentials when they are required. Increase sonar.scanner.connectTimeout, sonar.scanner.socketTimeout, or sonar.scanner.responseTimeout for slow but healthy connections. All values are in seconds.

Download failures

The scanner downloads a Java runtime and the analysis engine to <sonar.userHome>/cache, where sonar.userHome defaults to ~/.sonar. Incomplete or corrupted downloads are never installed, and a checksum mismatch is retried once. If it still fails, investigate the network, proxy, or TLS interception before clearing the cache. To skip Java provisioning altogether, see Managing JRE auto-provisioning.

Related pages

PreviousSonarScanner for Python
NextSonarScanner CLI

Last updated

Was this helpful?