Skip to end of metadata
Go to start of metadata

Table of Contents

The SonarQube Scanner is recommended as the default launcher to analyze a project with SonarQube.


You must have previously installed the SonarQube Scanner and read Analyzing Code Source. You must also have the language plugins installed for each of the languages you wish to analyze in your projects. 


Simple Project

Create a configuration file in the root directory of the project:
# must be unique in a given SonarQube instance
# this is the name displayed in the SonarQube UI
sonar.projectName=My project

# Path is relative to the file. Replace "\" by "/" on Windows.
# Since SonarQube 4.2, this property is optional if sonar.modules is set. 
# If not set, SonarQube starts looking for source code from the directory containing 
# the file.

# Encoding of the source code. Default is default system encoding

Run the following command from the project base directory to launch the analysis:



Any user who's granted Execute Analysis permission can run an analysis.

If the Anyone group is not granted Execute Analysis permission or if the SonarQube instance is secured (the sonar.forceAuthentication property is set to true), the credentials of a user having been granted Execute Analysis permission have to be provided through the sonar.login and sonar.password properties. Example: sonar-runner -Dsonar.login=myLogin -Dsonar.password=myPassword

Note that for a preview analysis, the user also has to be granted the Browse permission on the project to be analyzed.

Project Samples

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 projects/languages.

Multi-language Project

Since SonarQube 4.2, it is possible to run an analysis on a multi-language project. To do so, the sonar.language property just has to be removed. Conversely, if for some reason you want to perform a single language-only analysis, make sure sonar.language is specified.

To help you get started, a multi-language project sample can be browsed or downloaded from github: projects/languages/multi-language/multi-language-java-javascript-sonar-runner

Converting a Mono-language Project to a Multi-language Project

Let's take as an example a project containing both Java and JavaScript source code. Your SonarQube instance currently contains two different projects: one for the Java source code and one for the JavaScript source code. Optionally, you may also have created a view to aggregate these two projects.

The first step is to choose which one of these two mono-language projects you will convert to a multi-language project. You will lose the history (timeline, false positives, action plans, etc.) on the one that won't get converted to a multi-language project. In this example, we'll choose to convert the Java project to a multi-language project as most of our code (and therefore history) is Java.

The second step is to run another analysis of this Java project the old way (make sure to explicitly set the sonar.language property to java). This step is mandatory to keep the history on the project.

The third and last step is to remove the sonar.language property and set the sonar.sources property to the parent directory containing all your source code (Java + JavaScript). You can now run another analysis. You will finally be able to browse your first multi-language project!

Multi-module Project

There are two ways to define a multi-module structure in SonarQube:

 Using the given file structure...... with the given 'properties' files

Way #1

Set all the configuration in the properties file in the root folder

"MyProject/" file content
# Root project information
sonar.projectName=My Project

# Some properties that will be inherited by the modules

# List of the module identifiers

# Properties can obviously be overriden for
# each module - just prefix them with the module ID
module1.sonar.projectName=Module 1
module2.sonar.projectName=Module 2

Way #2

Set the configuration in multiple properties files

"MyProject/" file content
# Root project information
sonar.projectName=My Project

# Some properties that will be inherited by the modules

# List of the module identifiers
"MyProject/module1/" file content
# Redefine properties
# Note that you do not need to prefix the property here
sonar.projectName=Module 1
"MyProject/module2/" file content
# Redefine properties
# Note that you do not need to prefix the property here
sonar.projectName=Module 2



  • Children inherit their parent's properties 
    Inherited properties can be overriden:
    • By prefixing them with the module identifier (way #1)
    • Simply by defining them in the file located in the module (way #2)

  • Module base directory can be specified for special cases
    By default, the module base directory is guessed from the module identifier (like in the examples above). But it can be redefined using the sonar.projectBaseDir property.
    For instance, here are two use cases and how to redefine the base directory of the modules in each:
    • the folder of a module contains white spaces or special characters:

      module1.sonar.projectBaseDir=My Module One


    • the module is not located directly in the parent folder, but in a deeper directory structure:



  • A project that defines modules (or a module that defines sub-modules) cannot define a source code folder to be analyzed.

To help you get started, multi-module project samples can be browsed or downloaded from github:

  • Modules with the same structure: projects/multi-module/sonar-runner/java-sonar-runner-modules-same-structure
  • Modules with different structures: projects/multi-module/sonar-runner/java-sonar-runner-modules-different-structures
  • A configuration file for each module: projects/multi-module/sonar-runner/java-sonar-runner-modules-own-configuration-file

Running Other Tasks

# To run the computation of views (Views plugin is required)
sonar-runner views

# To run the computation of reports (Report plugin is required)
sonar-runner report

# To run the computation of developer data (Developer Cockpit plugin is required)
sonar-runner devcockpit

Advanced Usage

If a 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. Ex:

    sonar-runner -Dsonar.projectKey=myproject -Dsonar.sources=src1


  • The property project.settings can be used to specify the path to the project configuration file (this option is incompatible with the project.home and sonar.projectBaseDir properties). Ex:

    sonar-runner -Dproject.settings=../


The root folder of the project to analyze can be set through the sonar.projectBaseDir property since SonarQube Scanner 2.4 (was previously project.home). This folder must contain a file if the mandatory properties (like sonar.projectKey) are 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.

For more, see the listing of analysis parameters.


If you get a Java heap space error or java.lang.OutOfMemoryError, you can increase the memory via the SONAR_RUNNER_OPTS environment variable:

export SONAR_RUNNER_OPTS="-Xmx512m -XX:MaxPermSize=128m"

On Windows environments, avoid the double-quotes, since they get misinterpreted and combine the two parameters into a single one.

set SONAR_RUNNER_OPTS=-Xmx512m -XX:MaxPermSize=128m
  • No labels