SonarQube Getting Started: Setup, Analysis, and First Scan (2026)

Getting started overview

Getting started with SonarQube involves setting up a SonarQube server, configuring your project for analysis, and then executing a scan of your codebase. This process typically requires administrative access to a server for installation and basic command-line proficiency for running scanners. SonarQube supports various programming languages and integrates with common build systems and continuous integration/continuous delivery (CI/CD) pipelines.

The foundational components of a SonarQube setup include:

• SonarQube Server: The central hub that processes analysis reports, stores data, and hosts the user interface.
• Database: A relational database (e.g., PostgreSQL, MySQL, MS SQL Server, Oracle) used by the SonarQube Server to store analysis results and configuration.
• SonarScanner: A command-line tool or build system plugin that analyzes source code and sends the results to the SonarQube Server.

This guide will focus on setting up the self-hosted SonarQube Community Edition, which is available for free, and performing an initial code scan. Paid editions (Developer, Enterprise, Data Center) offer additional features like advanced security analysis, branch analysis, and scalability options, as detailed on the SonarQube downloads page.

Quick reference table

Create an account and get keys

For a self-hosted SonarQube instance, account creation and key generation are handled within your deployed SonarQube server's web interface. There isn't a central SaaS-style signup process.

1. Install and start the SonarQube server

Before you can create accounts or generate keys, the SonarQube server must be running. Here's a summary of the installation process:

1. Prerequisites: Ensure your system meets the requirements. SonarQube 9.9 LTS and newer requires Java 17 JRE or JDK. You'll also need a supported database (e.g., PostgreSQL 9.6 to 14, MySQL 5.6 to 8.0, MS SQL Server 2014 to 2019) and sufficient system resources.
2. Download SonarQube: Get the latest SonarQube Community Edition.
3. Extract: Unzip the downloaded file into your chosen directory (e.g., /opt/sonarqube). This directory will be referred to as SONARQUBE_HOME.
4. Database Setup: Create a dedicated database and user for SonarQube in your chosen database system. Configure SonarQube to connect to it by editing SONARQUBE_HOME/conf/sonar.properties. Refer to the official SonarQube installation documentation for specific database configurations.
5. Start SonarQube: Navigate to SONARQUBE_HOME/bin/[YOUR_OS] and execute the startup script (e.g., ./sonar.sh start for Linux/macOS or StartSonar.bat for Windows).

Allow a few minutes for the server to start. You can monitor the logs in SONARQUBE_HOME/logs/sonar.log.

2. Initial login and administrator account setup

Once the server is running, open your web browser and navigate to http://localhost:9000 (or your server's IP/hostname on port 9000). The default administrator credentials are Username: admin and Password: admin. Upon first login, you will be prompted to change the default administrator password for security reasons.

3. Generate a user token (API Key)

To allow SonarScanners or other tools to interact with your SonarQube server, you'll generate a user token. This token acts as an API key for authentication.

1. Log into the SonarQube web interface.
2. Click on your user icon in the top right corner and select My Account.
3. Go to the Security tab.
4. Under 'Generate Tokens', provide a name for your token (e.g., my-project-scanner-token) and click Generate.
5. Copy the generated token immediately. It will only be displayed once. This token will be used by the SonarScanner to authenticate with your SonarQube server during analysis.

This token should be treated as a sensitive credential and stored securely, similar to an API key for a cloud service.

Your first request

A "request" in SonarQube typically refers to running a code analysis, which sends the results to the SonarQube server. This is done using a SonarScanner.

1. Install SonarScanner

Download the appropriate SonarScanner for your environment. The most common is the SonarScanner CLI. Extract it to a directory (e.g., C:\SonarScanner or /opt/sonar-scanner) and add its bin directory to your system's PATH environment variable.

Verify the installation by opening a new terminal or command prompt and running sonar-scanner -h. You should see the help output for the scanner.

2. Create a new project in SonarQube

1. In the SonarQube web UI, click the Projects tab.
2. Click Create Project.
3. Choose Manually.
4. Enter a Project Key (a unique identifier, e.g., my-first-java-project) and a Display Name (e.g., My First Java Project). Click Set Up.
5. On the next screen, select With a local analysis.
6. Choose your project's primary language.
7. Under 'Provide your token', select 'Use the token I already generated' and paste the token generated earlier. Click Continue.
8. SonarQube will then display the command-line instructions needed to run the analysis for your project. Copy these commands.

3. Prepare your project for analysis

Navigate to the root directory of the source code you wish to analyze in your terminal or command prompt. For a simple demonstration, you might create a basic Java file (e.g., HelloWorld.java) with some intentional code smells or vulnerabilities to see how SonarQube identifies them.

4. Run the first analysis

Paste and execute the SonarScanner commands you copied from the SonarQube UI into your project's root directory. The command will typically look like this (adjusting for your token, project key, and server URL):

sonar-scanner \
  -Dsonar.projectKey=my-first-java-project \
  -Dsonar.sources=. \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=YOUR_GENERATED_TOKEN

The scanner will execute, analyze your files, and then send the results to your SonarQube server. This process can take a few minutes depending on the size of your codebase and system resources. You will see progress messages in your terminal.

5. View analysis results

Once the scanner completes, refresh your SonarQube web interface. Your newly analyzed project should appear on the projects dashboard. Click on the project name to view its detailed analysis report, including metrics for bugs, vulnerabilities, code smells, and technical debt. For instance, the Mozilla Developer Network's definition of code smell aligns with issues SonarQube would flag.

Common next steps

After successfully running your first analysis, consider these common next steps to integrate SonarQube further into your development workflow:

• Integrate with CI/CD: Automate code analysis as part of your build pipeline (e.g., Jenkins, GitLab CI, GitHub Actions, Azure DevOps). SonarQube offers specific documentation for various CI platforms.
• Configure Quality Gates: Define criteria that your code must meet before it's considered releasable. Quality Gates can fail a build if new code introduces critical issues, preventing regressions.
• Explore Quality Profiles: Customize the set of rules (e.g., for Java, JavaScript, Python) that SonarQube uses for analysis. You can enable or disable specific rules or create entirely new profiles to match your project's coding standards.
• Install Language Plugins: If your project uses languages not supported by default, explore and install additional SonarQube plugins from the marketplace.
• User and Group Management: Set up additional user accounts and groups with appropriate permissions for team members.
• IDE Integration: Install SonarLint (an IDE extension) to get real-time feedback on code quality and security issues directly within your development environment (e.g., IntelliJ IDEA, VS Code, Eclipse).
• Review and Prioritize Issues: Regularly review the issues reported by SonarQube, prioritize them based on severity and impact, and integrate remediation into your development sprints.

Troubleshooting the first call

If your first SonarScanner analysis fails or doesn't report results as expected, here are common areas to troubleshoot:

• SonarQube Server Status: Verify that the SonarQube server is running. Check the SONARQUBE_HOME/logs/sonar.log file for any startup errors.
• Database Connection: Ensure your database is running and accessible, and that the connection details in sonar.properties are correct. Database connection issues are a frequent cause of server startup failures.
• Java Version: Confirm that the correct Java version (JRE or JDK 17 for SonarQube 9.9+) is installed and that the JAVA_HOME environment variable is set correctly for both the SonarQube server and the SonarScanner.
• SonarScanner PATH: Make sure the SonarScanner's bin directory is included in your system's PATH environment variable, or use the full path to the sonar-scanner executable.
• Server URL: Double-check the -Dsonar.host.url parameter in your scanner command. It must point to your running SonarQube server (e.g., http://localhost:9000).
• Authentication Token: Ensure the -Dsonar.token parameter uses the correct, currently valid user token generated from your SonarQube server. If the token is incorrect or expired, the scanner will fail to authenticate.
• Project Key: Verify that the -Dsonar.projectKey matches the key you defined when creating the project in the SonarQube UI.
• Analysis Scope (sonar.sources): The -Dsonar.sources=. parameter tells the scanner to analyze the current directory. If your source code is in a subdirectory, adjust this parameter accordingly (e.g., -Dsonar.sources=src).
• Firewall Rules: Ensure that no firewall is blocking traffic to port 9000 (or your configured port) on the SonarQube server.
• Scanner Logs: Review the output of the sonar-scanner command in your terminal. It often provides specific error messages that can guide your troubleshooting. You can increase the logging verbosity by adding -Dsonar.log.level=DEBUG to the scanner command.