Running NVDA from Source

Overview

Running NVDA from source is the most efficient way to develop and test changes. You can launch NVDA directly without building installers or portable distributions.

Running from source requires completing the setup guide and preparing the source tree first.

Prerequisites

Before running from source:

Complete environment setup

Install Python 3.13.12, Visual Studio 2022/2026, and uv as described in the setup guide

Clone the repository

Clone with --recursive to include all submodules:

git clone --recursive https://github.com/YOUR-USERNAME/nvda.git

Prepare the source tree

Build C++ components and prepare dependencies:

scons source

Launching NVDA from Source

Once the source tree is prepared, launch NVDA using the batch file:

runnvda.bat

This starts NVDA with your source code changes immediately.

What Happens When You Run

The runnvda.bat script:

Activates the Python virtual environment
Sets up the correct Python path to use source/ directory
Launches the NVDA Python application
Loads all compiled C++ components (nvdaHelper DLLs)
Initializes the screen reader with current source code

Changes to Python files (.py) are reflected immediately on the next launch. Changes to C++ code require rebuilding with scons source.

Command Line Options

NVDA accepts numerous command-line arguments for testing and debugging:

View Available Options

runnvda.bat --help

runnvda.bat -h

Common Options

-c CONFIG_PATH

path

Use a specific configuration directory

runnvda.bat -c "C:\temp\nvda-config"

Useful for testing with clean configuration or multiple configurations.

--disable-addons

boolean

Start NVDA without loading any add-ons

runnvda.bat --disable-addons

Helpful for isolating issues caused by add-ons.

--debug-logging

boolean

Enable debug-level logging

runnvda.bat --debug-logging

Provides detailed logs for troubleshooting.

--log-file LOG_FILE

path

Specify custom log file location

runnvda.bat --log-file="C:\temp\nvda.log"

--log-level LOG_LEVEL

string

Set logging level (DEBUG, IO, INFO, WARNING, ERROR)

runnvda.bat --log-level=DEBUG

-r

boolean

Restart NVDA after it exits

runnvda.bat -r

--no-sr-flag

boolean

Don’t set the system screen reader flag

runnvda.bat --no-sr-flag

Allows running alongside another screen reader.

Example: Clean Testing Environment

Test with a fresh configuration:

runnvda.bat -c "C:\temp\nvda-test-config" --disable-addons --debug-logging

This:

Uses a temporary configuration directory
Disables all add-ons
Enables verbose debug logging

Development Workflow

Typical Development Cycle

Make code changes

Edit Python files in the source/ directory or C++ files in nvdaHelper/

Rebuild if needed

For C++ changes:

scons source

For Python changes, no rebuild needed.

Launch NVDA

runnvda.bat

Test your changes

Interact with applications and verify your modifications work correctly

Check logs

Review logs for errors or warnings:

notepad %TEMP%\nvda.log

Iterate

Exit NVDA, make adjustments, and relaunch to test again

Testing Scenarios

Testing with Multiple Configurations

Maintain separate configuration directories for different testing scenarios:

# Test with minimal configuration
runnvda.bat -c "C:\nvda-configs\minimal"

# Test with specific add-ons
runnvda.bat -c "C:\nvda-configs\with-addons"

# Test with complex settings
runnvda.bat -c "C:\nvda-configs\advanced"

Testing Braille Displays

Run with braille debugging:

runnvda.bat --debug-logging --log-level=IO

The IO log level includes input/output operations for braille devices.

Testing Speech Synthesizers

Test specific speech synthesizer:

runnvda.bat --debug-logging

Then change synthesizer in NVDA settings.

Testing Startup Behavior

Test NVDA’s startup sequence:

runnvda.bat --log-level=INFO --log-file="C:\temp\startup.log"

Debugging Techniques

Using Python Debugger

Attach a Python debugger to inspect code execution:

# Add to any Python file in source/
import debugpy
debugpy.listen(5678)
debugpy.wait_for_client()

Then connect with VS Code or another debugger on port 5678.

Logging and Print Statements

Add logging to track execution:

import logging
log = logging.getLogger(__name__)

def myFunction():
    log.debug("Entering myFunction")
    # Your code here
    log.debug(f"Variable value: {someVar}")

Viewing Real-Time Logs

Monitor logs while NVDA runs:

# PowerShell
Get-Content $env:TEMP\nvda.log -Wait -Tail 50

# Command Prompt (using PowerShell)
powershell -Command "Get-Content $env:TEMP\nvda.log -Wait -Tail 50"

Performance Considerations

Python Bytecode Caching

Python automatically creates .pyc bytecode files in source/__pycache__/.

Sometimes stale bytecode can cause unexpected behavior. If you encounter strange issues, delete the cache:

rmdir /s /q source\__pycache__

Development vs. Release Performance

Running from source is slower than release builds because:

Python code isn’t optimized with -O flag
No whole-program optimization for C++ components
Debug symbols are present
Additional runtime checks are enabled

For performance testing, create a release build with scons launcher release=1

Common Issues

NVDA won't start after changes

Check for Python syntax errors:

python -m py_compile source\path\to\modified_file.py

Review the log file:

notepad %TEMP%\nvda.log

Changes not reflected when running

For Python files:

Ensure you saved the file
Delete bytecode cache if present
Restart NVDA

For C++ files:

scons source
runnvda.bat

Import errors for dependencies

The virtual environment may be outdated:

scons -c source
scons source

NVDA crashes immediately

Check for missing DLLs or corrupted build:

scons -c
scons source
runnvda.bat

Review crash log in %TEMP%\nvda-crash.log

COM interface errors

Rebuild COM interfaces:

scons -c source\comInterfaces
scons source

Can't run multiple instances

By default, NVDA prevents multiple instances. To run multiple instances for testing:

runnvda.bat -c "C:\temp\instance1" --no-sr-flag
runnvda.bat -c "C:\temp\instance2" --no-sr-flag

Building vs. Running from Source

When to Use Each Approach

Run from Source

Use for:

Daily development
Quick testing
Debugging
Python-only changes

Command: runnvda.bat

Build Binary

Use for:

Release testing
Performance validation
Distribution
Installing on other systems

Command: scons launcher

Testing Best Practices

1. Use Separate Configuration Directories

Never test with your personal NVDA configuration:

runnvda.bat -c "C:\nvda-dev-config"

2. Enable Debug Logging by Default

Create a batch file for development:

@echo off
runnvda.bat -c "C:\nvda-dev" --debug-logging --log-level=DEBUG

Save as dev-run.bat in the repository root.

3. Test with Add-ons Disabled

First verify issues without add-ons:

runnvda.bat --disable-addons

4. Document Test Scenarios

Create batch files for common test scenarios:

:: test-minimal.bat
runnvda.bat -c "%TEMP%\nvda-minimal" --disable-addons

:: test-braille.bat
runnvda.bat -c "%TEMP%\nvda-braille" --log-level=IO

:: test-speech.bat
runnvda.bat -c "%TEMP%\nvda-speech" --debug-logging

5. Review Logs After Testing

Always check logs for warnings or errors:

findstr /I "error warning exception" %TEMP%\nvda.log

Accessing User Documentation

If you need user documentation available in the Help menu:

scons source user_docs
runnvda.bat

Building user documentation is slower. Skip it for routine development unless you’re specifically testing documentation features.

Next Steps

Building NVDA

Learn how to create binary builds and installers

Development Overview

Understand NVDA’s architecture and workflow

GitHub Repository

Browse the source code and submit contributions

Command Line Options

Full list of command-line arguments

Getting Started

Contributing

Architecture

Add-on Development

Advanced Topics

​Overview

​Prerequisites

​Launching NVDA from Source

​What Happens When You Run

​Command Line Options

​View Available Options

​Common Options

​Example: Clean Testing Environment

​Development Workflow

​Typical Development Cycle

​Testing Scenarios

​Testing with Multiple Configurations

​Testing Braille Displays

​Testing Speech Synthesizers

​Testing Startup Behavior

​Debugging Techniques

​Using Python Debugger

​Logging and Print Statements

​Viewing Real-Time Logs

​Performance Considerations

​Python Bytecode Caching

​Development vs. Release Performance

​Common Issues

​Building vs. Running from Source

​When to Use Each Approach

Run from Source

Build Binary

​Testing Best Practices

​1. Use Separate Configuration Directories

​2. Enable Debug Logging by Default

​3. Test with Add-ons Disabled

​4. Document Test Scenarios

​5. Review Logs After Testing

​Accessing User Documentation

​Next Steps

Building NVDA

Development Overview

GitHub Repository

Command Line Options

Build docs developers (and LLMs) love

Overview

Prerequisites

Launching NVDA from Source

What Happens When You Run

Command Line Options

View Available Options

Common Options

Example: Clean Testing Environment

Development Workflow

Typical Development Cycle

Testing Scenarios

Testing with Multiple Configurations

Testing Braille Displays

Testing Speech Synthesizers

Testing Startup Behavior

Debugging Techniques

Using Python Debugger

Logging and Print Statements

Viewing Real-Time Logs

Performance Considerations

Python Bytecode Caching

Development vs. Release Performance

Common Issues

Building vs. Running from Source

When to Use Each Approach

Testing Best Practices

1. Use Separate Configuration Directories

2. Enable Debug Logging by Default

3. Test with Add-ons Disabled

4. Document Test Scenarios

5. Review Logs After Testing

Accessing User Documentation

Next Steps