Running NVDA from Source

How to run and test NVDA directly from source code without creating full binary builds

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:

1. Complete environment setup

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

2. Clone the repository

   Clone with --recursive to include all submodules:

   git clone --recursive https://github.com/YOUR-USERNAME/nvda.git
   
3. 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:

1. Activates the Python virtual environment
2. Sets up the correct Python path to use source/ directory
3. Launches the NVDA Python application
4. Loads all compiled C++ components (nvdaHelper DLLs)
5. 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

or

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

1. Make code changes

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

2. Rebuild if needed

   For C++ changes:

   scons source
   

   For Python changes, no rebuild needed.

3. Launch NVDA

   runnvda.bat
   
4. Test your changes

   Interact with applications and verify your modifications work correctly

5. Check logs

   Review logs for errors or warnings:

   notepad %TEMP%\nvda.log
   
6. 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