Skip to main content

​
Prerequisites

Before building NVDA, ensure you have:
All build commands should be run from the root directory of the NVDA repository in a command prompt or PowerShell.

​
Preparing the Source Tree

Before running NVDA or creating builds, you must prepare the source tree: 
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: 
scons source user_docs
Building user documentation is slower because it regenerates each time the revision number changes. For routine development, scons source alone is faster.

​
Build Performance Optimization

Speed up builds by using multiple CPU cores:

​
Using Specific Core Count

scons source -j 4
Replace 4 with the number of cores you want to use.

​
Using All Available Cores

scons source --all-cores
Building across multiple cores can cause scrambled output and occasionally build errors.

​
Troubleshooting Build Errors

If you experience errors with multi-threaded builds, force a serial build: 
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: 
runnvda.bat

​
Command Line Options

View all available options: 
runnvda.bat -h
or 
runnvda.bat --help
These arguments are documented in the NVDA user guide.
Running from source is the fastest way to test changes during development. You don’t need to create full binary builds for routine testing.

​
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: 
scons dist
The build is created in the dist/ directory.
This is equivalent to an extracted portable archive and useful for testing the full distribution without creating installer packages.

​
Building the Installer

Create a launcher archive (one executable that allows installation or portable distribution): 
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: 
scons symbolsArchive
Output: output/nvda_<version>_debugSymbols.zip
Debug symbols are essential for analyzing crash dumps and debugging release builds.

​
Translation Template

Generate a gettext translation template for translators: 
scons pot
Output: output/nvda.pot

​
Controller Client

Build the controller client library: 
scons client
Output: output/nvda_<version>_controllerClient.zip

​
Developer Documentation

Generate developer documentation (requires Doxygen): 
scons devDocs

​
Customizing Builds

Build behavior can be customized using command-line variables:

​
Available Build Variables

​
version
string
The version of this build
scons launcher version=2024.1.0
​
version_build
string
default:"0"
A unique number for this build
scons launcher version_build=12345
​
release
boolean
default:"false"
Whether this is a release versionEnables:
  • C++ compiler optimizations (/O2)
  • Whole-program optimization
  • Optimized Python bytecode
scons launcher release=1
​
publisher
string
The publisher of this build
scons launcher publisher="My Organization"
​
certFile
path
Certificate file for code signing (PFX format with private key)
scons launcher certFile=certificate.pfx
​
certPassword
string
Password for the signing certificate’s private key
scons launcher certFile=cert.pfx certPassword=mypassword
​
certTimestampServer
url
URL of the timestamping server for authenticode signatures
scons launcher certFile=cert.pfx certTimestampServer=http://timestamp.digicert.com
​
outputDir
path
default:"output"
Directory where final built archives are placed
scons launcher outputDir=releases

​
Example: Custom Version Build

scons launcher version=test1
This creates a launcher named nvda_snapshot_test1.exe in the output/ directory.

​
Example: Signed Release Build

scons launcher release=1 certFile=mycert.pfx certPassword=secret certTimestampServer=http://timestamp.digicert.com
Code signing requires a valid code signing certificate. For production releases, NV Access uses their own certificate.

​
Build Targets Summary

source

Prepare source tree for development
scons source

dist

Create non-archived binary build
scons dist

launcher

Build installer executable
scons launcher

symbolsArchive

Generate debug symbols archive
scons symbolsArchive

pot

Create translation template
scons pot

client

Build controller client
scons client

​
Build System Details

​
SCons Build System

NVDA uses SCons 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:
SCons must be executed through scons.bat from the repository root. Running SCons directly from outside the virtual environment will fail.

​
Advanced Build Configuration

​
nvdaHelper Debug Flags

For C++ component debugging: 
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): 
scons source nvdaHelperLogLevel=10
Default: 15

​
Cleaning Builds

Remove built files: 
scons -c
Clean specific targets: 
scons -c dist
scons -c launcher

​
Troubleshooting

Always use scons.bat from the repository root, not the system-wide SCons command:
# Correct
scons source

# Incorrect
python -m SCons source
Force single-threaded build:
scons source -j 1
Rebuild the source tree:
scons -c source
scons source
Verify all required components are installed:
where cl.exe
where link.exe
Should show paths to Visual Studio 2022 or 2026 build tools.
Ensure:
  • Certificate file exists and is in PFX format
  • Certificate password is correct
  • Timestamp server is accessible
  • Certificate is valid for code signing

​
Next Steps

Running from Source

Learn how to run and test NVDA from source

Development Overview

Understand NVDA’s architecture and development workflow

​
Additional Resources

For more details, see:
  • sconstruct (line 1-720 in /home/daytona/workspace/source/sconstruct)
  • projectDocs/dev/buildingNVDA.md in the source tree

Build docs developers (and LLMs) love

Get started for freeTalk to us