> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nvaccess/nvda/llms.txt
> Use this file to discover all available pages before exploring further.

# Building NVDA

> Comprehensive guide to building NVDA from source, including preparing the source tree, creating binary builds, and customizing builds

## Prerequisites

Before building NVDA, ensure you have:

* [Completed the development environment setup](/development/setup)
* Cloned the NVDA repository with submodules
* Installed Python 3.13.12, Visual Studio 2022/2026, and uv

<Note>
  All build commands should be run from the root directory of the NVDA repository in a command prompt or PowerShell.
</Note>

## Preparing the Source Tree

Before running NVDA or creating builds, you must prepare the source tree:

```cmd theme={null}
scons source
```

This command:

* Compiles C++ components (nvdaHelper)
* Generates COM interfaces
* Processes dependencies
* Sets up the development environment

### When to Rebuild

Run `scons source` again whenever:

* The version of comtypes changes
* Language files are added or changed
* Git submodules are updated
* C++ code in nvdaHelper is modified

### Including User Documentation

To access user documentation from the Help menu while running from source:

```cmd theme={null}
scons source user_docs
```

<Warning>
  Building user documentation is slower because it regenerates each time the revision number changes. For routine development, `scons source` alone is faster.
</Warning>

## Build Performance Optimization

Speed up builds by using multiple CPU cores:

### Using Specific Core Count

```cmd theme={null}
scons source -j 4
```

Replace `4` with the number of cores you want to use.

### Using All Available Cores

```cmd theme={null}
scons source --all-cores
```

<Note>
  Building across multiple cores can cause scrambled output and occasionally build errors.
</Note>

### Troubleshooting Build Errors

If you experience errors with multi-threaded builds, force a serial build:

```cmd theme={null}
scons source -j 1
```

This makes tracking down issues easier and may resolve intermittent errors.

## Running the Source Code

After preparing the source tree, launch NVDA directly from source:

```cmd theme={null}
runnvda.bat
```

### Command Line Options

View all available options:

```cmd theme={null}
runnvda.bat -h
```

or

```cmd theme={null}
runnvda.bat --help
```

These arguments are documented in the [NVDA user guide](https://download.nvaccess.org/documentation/userGuide.html#CommandLineOptions).

<Tip>
  Running from source is the fastest way to test changes during development. You don't need to create full binary builds for routine testing.
</Tip>

## Making Binary Builds

Binary builds can run on systems without Python or NVDA's development dependencies. These are used for snapshots and releases.

### Non-Archived Binary Build

Create a portable build without archiving:

```cmd theme={null}
scons dist
```

The build is created in the `dist/` directory.

<Note>
  This is equivalent to an extracted portable archive and useful for testing the full distribution without creating installer packages.
</Note>

### Building the Installer

Create a launcher archive (one executable that allows installation or portable distribution):

```cmd theme={null}
scons launcher
```

The launcher executable is placed in the `output/` directory.

**File naming:**

* Release builds: `nvda_<version>.exe`
* Snapshot builds: `nvda_snapshot_<version>.exe`

### Additional Build Targets

#### Debug Symbols Archive

Generate an archive of debug symbols for DLL/EXE binaries:

```cmd theme={null}
scons symbolsArchive
```

Output: `output/nvda_<version>_debugSymbols.zip`

<Note>
  Debug symbols are essential for analyzing crash dumps and debugging release builds.
</Note>

#### Translation Template

Generate a gettext translation template for translators:

```cmd theme={null}
scons pot
```

Output: `output/nvda.pot`

#### Controller Client

Build the controller client library:

```cmd theme={null}
scons client
```

Output: `output/nvda_<version>_controllerClient.zip`

#### Developer Documentation

Generate developer documentation (requires Doxygen):

```cmd theme={null}
scons devDocs
```

## Customizing Builds

Build behavior can be customized using command-line variables:

### Available Build Variables

<ParamField path="version" type="string">
  The version of this build

  ```cmd theme={null}
  scons launcher version=2024.1.0
  ```
</ParamField>

<ParamField path="version_build" type="string" default="0">
  A unique number for this build

  ```cmd theme={null}
  scons launcher version_build=12345
  ```
</ParamField>

<ParamField path="release" type="boolean" default="false">
  Whether this is a release version

  Enables:

  * C++ compiler optimizations (/O2)
  * Whole-program optimization
  * Optimized Python bytecode

  ```cmd theme={null}
  scons launcher release=1
  ```
</ParamField>

<ParamField path="publisher" type="string">
  The publisher of this build

  ```cmd theme={null}
  scons launcher publisher="My Organization"
  ```
</ParamField>

<ParamField path="certFile" type="path">
  Certificate file for code signing (PFX format with private key)

  ```cmd theme={null}
  scons launcher certFile=certificate.pfx
  ```
</ParamField>

<ParamField path="certPassword" type="string">
  Password for the signing certificate's private key

  ```cmd theme={null}
  scons launcher certFile=cert.pfx certPassword=mypassword
  ```
</ParamField>

<ParamField path="certTimestampServer" type="url">
  URL of the timestamping server for authenticode signatures

  ```cmd theme={null}
  scons launcher certFile=cert.pfx certTimestampServer=http://timestamp.digicert.com
  ```
</ParamField>

<ParamField path="outputDir" type="path" default="output">
  Directory where final built archives are placed

  ```cmd theme={null}
  scons launcher outputDir=releases
  ```
</ParamField>

### Example: Custom Version Build

```cmd theme={null}
scons launcher version=test1
```

This creates a launcher named `nvda_snapshot_test1.exe` in the `output/` directory.

### Example: Signed Release Build

```cmd theme={null}
scons launcher release=1 certFile=mycert.pfx certPassword=secret certTimestampServer=http://timestamp.digicert.com
```

<Warning>
  Code signing requires a valid code signing certificate. For production releases, NV Access uses their own certificate.
</Warning>

## Build Targets Summary

<CardGroup cols={2}>
  <Card title="source" icon="code">
    Prepare source tree for development

    ```cmd theme={null}
    scons source
    ```
  </Card>

  <Card title="dist" icon="folder">
    Create non-archived binary build

    ```cmd theme={null}
    scons dist
    ```
  </Card>

  <Card title="launcher" icon="rocket">
    Build installer executable

    ```cmd theme={null}
    scons launcher
    ```
  </Card>

  <Card title="symbolsArchive" icon="bug">
    Generate debug symbols archive

    ```cmd theme={null}
    scons symbolsArchive
    ```
  </Card>

  <Card title="pot" icon="language">
    Create translation template

    ```cmd theme={null}
    scons pot
    ```
  </Card>

  <Card title="client" icon="plug">
    Build controller client

    ```cmd theme={null}
    scons client
    ```
  </Card>
</CardGroup>

## Build System Details

### SCons Build System

NVDA uses [SCons](https://scons.org/) version 4.10.1 as its build system. SCons is a Python-based build tool similar to Make.

**Key SCons files:**

* `sconstruct` - Main build configuration (720 lines)
* `*/sconscript` - Module-specific build scripts

### Build Architectures

NVDA builds components for multiple architectures:

* **x86** (32-bit) - Legacy Windows support
* **x86\_64** (64-bit) - Primary Windows architecture
* **ARM64** - Native ARM Windows support
* **ARM64EC** - ARM64 with x64 emulation compatibility

### Python Virtual Environment

The build system automatically creates and manages a Python virtual environment:

<Note>
  SCons must be executed through `scons.bat` from the repository root. Running SCons directly from outside the virtual environment will fail.
</Note>

## Advanced Build Configuration

### nvdaHelper Debug Flags

For C++ component debugging:

```cmd theme={null}
scons source nvdaHelperDebugFlags=debugCRT,RTC
```

Available flags:

* `debugCRT` - Use debug C runtime
* `RTC` - Runtime checks
* `analyze` - Static analysis

### nvdaHelper Log Level

Control logging verbosity (0-59, lower is more verbose):

```cmd theme={null}
scons source nvdaHelperLogLevel=10
```

Default: 15

## Cleaning Builds

Remove built files:

```cmd theme={null}
scons -c
```

Clean specific targets:

```cmd theme={null}
scons -c dist
scons -c launcher
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Build fails with 'SCons was started outside virtual environment'">
    Always use `scons.bat` from the repository root, not the system-wide SCons command:

    ```cmd theme={null}
    # Correct
    scons source

    # Incorrect
    python -m SCons source
    ```
  </Accordion>

  <Accordion title="Multi-threaded build produces errors">
    Force single-threaded build:

    ```cmd theme={null}
    scons source -j 1
    ```
  </Accordion>

  <Accordion title="Comtypes changes not reflected">
    Rebuild the source tree:

    ```cmd theme={null}
    scons -c source
    scons source
    ```
  </Accordion>

  <Accordion title="Missing Visual Studio components">
    Verify all required components are installed:

    ```cmd theme={null}
    where cl.exe
    where link.exe
    ```

    Should show paths to Visual Studio 2022 or 2026 build tools.
  </Accordion>

  <Accordion title="Code signing fails">
    Ensure:

    * Certificate file exists and is in PFX format
    * Certificate password is correct
    * Timestamp server is accessible
    * Certificate is valid for code signing
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Running from Source" icon="play" href="/development/running-from-source">
    Learn how to run and test NVDA from source
  </Card>

  <Card title="Development Overview" icon="book" href="/development/overview">
    Understand NVDA's architecture and development workflow
  </Card>
</CardGroup>

## Additional Resources

For more details, see:

* `sconstruct` (line 1-720 in `/home/daytona/workspace/source/sconstruct`)
* `projectDocs/dev/buildingNVDA.md` in the source tree