> ## 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.

# 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.

<Note>
  Running from source requires completing the [setup guide](/development/setup) and [preparing the source tree](/development/building#preparing-the-source-tree) first.
</Note>

## Prerequisites

Before running from source:

<Steps>
  <Step title="Complete environment setup">
    Install Python 3.13.12, Visual Studio 2022/2026, and uv as described in the [setup guide](/development/setup)
  </Step>

  <Step title="Clone the repository">
    Clone with `--recursive` to include all submodules:

    ```bash theme={null}
    git clone --recursive https://github.com/YOUR-USERNAME/nvda.git
    ```
  </Step>

  <Step title="Prepare the source tree">
    Build C++ components and prepare dependencies:

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

## Launching NVDA from Source

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

```cmd theme={null}
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

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

## Command Line Options

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

### View Available Options

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

or

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

### Common Options

<ParamField path="-c CONFIG_PATH" type="path">
  Use a specific configuration directory

  ```cmd theme={null}
  runnvda.bat -c "C:\temp\nvda-config"
  ```

  Useful for testing with clean configuration or multiple configurations.
</ParamField>

<ParamField path="--disable-addons" type="boolean">
  Start NVDA without loading any add-ons

  ```cmd theme={null}
  runnvda.bat --disable-addons
  ```

  Helpful for isolating issues caused by add-ons.
</ParamField>

<ParamField path="--debug-logging" type="boolean">
  Enable debug-level logging

  ```cmd theme={null}
  runnvda.bat --debug-logging
  ```

  Provides detailed logs for troubleshooting.
</ParamField>

<ParamField path="--log-file LOG_FILE" type="path">
  Specify custom log file location

  ```cmd theme={null}
  runnvda.bat --log-file="C:\temp\nvda.log"
  ```
</ParamField>

<ParamField path="--log-level LOG_LEVEL" type="string">
  Set logging level (DEBUG, IO, INFO, WARNING, ERROR)

  ```cmd theme={null}
  runnvda.bat --log-level=DEBUG
  ```
</ParamField>

<ParamField path="-r" type="boolean">
  Restart NVDA after it exits

  ```cmd theme={null}
  runnvda.bat -r
  ```
</ParamField>

<ParamField path="--no-sr-flag" type="boolean">
  Don't set the system screen reader flag

  ```cmd theme={null}
  runnvda.bat --no-sr-flag
  ```

  Allows running alongside another screen reader.
</ParamField>

### Example: Clean Testing Environment

Test with a fresh configuration:

```cmd theme={null}
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

<Steps>
  <Step title="Make code changes">
    Edit Python files in the `source/` directory or C++ files in `nvdaHelper/`
  </Step>

  <Step title="Rebuild if needed">
    For C++ changes:

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

    For Python changes, no rebuild needed.
  </Step>

  <Step title="Launch NVDA">
    ```cmd theme={null}
    runnvda.bat
    ```
  </Step>

  <Step title="Test your changes">
    Interact with applications and verify your modifications work correctly
  </Step>

  <Step title="Check logs">
    Review logs for errors or warnings:

    ```cmd theme={null}
    notepad %TEMP%\nvda.log
    ```
  </Step>

  <Step title="Iterate">
    Exit NVDA, make adjustments, and relaunch to test again
  </Step>
</Steps>

## Testing Scenarios

### Testing with Multiple Configurations

Maintain separate configuration directories for different testing scenarios:

```cmd theme={null}
# 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:

```cmd theme={null}
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:

```cmd theme={null}
runnvda.bat --debug-logging
```

Then change synthesizer in NVDA settings.

### Testing Startup Behavior

Test NVDA's startup sequence:

```cmd theme={null}
runnvda.bat --log-level=INFO --log-file="C:\temp\startup.log"
```

## Debugging Techniques

### Using Python Debugger

Attach a Python debugger to inspect code execution:

```python theme={null}
# 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:

```python theme={null}
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 theme={null}
# PowerShell
Get-Content $env:TEMP\nvda.log -Wait -Tail 50
```

```cmd theme={null}
# 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__/`.

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

  ```cmd theme={null}
  rmdir /s /q source\__pycache__
  ```
</Warning>

### 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

<Note>
  For performance testing, create a release build with `scons launcher release=1`
</Note>

## Common Issues

<AccordionGroup>
  <Accordion title="NVDA won't start after changes">
    Check for Python syntax errors:

    ```cmd theme={null}
    python -m py_compile source\path\to\modified_file.py
    ```

    Review the log file:

    ```cmd theme={null}
    notepad %TEMP%\nvda.log
    ```
  </Accordion>

  <Accordion title="Changes not reflected when running">
    For Python files:

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

    For C++ files:

    ```cmd theme={null}
    scons source
    runnvda.bat
    ```
  </Accordion>

  <Accordion title="Import errors for dependencies">
    The virtual environment may be outdated:

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

  <Accordion title="NVDA crashes immediately">
    Check for missing DLLs or corrupted build:

    ```cmd theme={null}
    scons -c
    scons source
    runnvda.bat
    ```

    Review crash log in `%TEMP%\nvda-crash.log`
  </Accordion>

  <Accordion title="COM interface errors">
    Rebuild COM interfaces:

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

  <Accordion title="Can't run multiple instances">
    By default, NVDA prevents multiple instances. To run multiple instances for testing:

    ```cmd theme={null}
    runnvda.bat -c "C:\temp\instance1" --no-sr-flag
    runnvda.bat -c "C:\temp\instance2" --no-sr-flag
    ```
  </Accordion>
</AccordionGroup>

## Building vs. Running from Source

### When to Use Each Approach

<CardGroup cols={2}>
  <Card title="Run from Source" icon="play">
    **Use for:**

    * Daily development
    * Quick testing
    * Debugging
    * Python-only changes

    **Command:** `runnvda.bat`
  </Card>

  <Card title="Build Binary" icon="box">
    **Use for:**

    * Release testing
    * Performance validation
    * Distribution
    * Installing on other systems

    **Command:** `scons launcher`
  </Card>
</CardGroup>

## Testing Best Practices

### 1. Use Separate Configuration Directories

Never test with your personal NVDA configuration:

```cmd theme={null}
runnvda.bat -c "C:\nvda-dev-config"
```

### 2. Enable Debug Logging by Default

Create a batch file for development:

```batch theme={null}
@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:

```cmd theme={null}
runnvda.bat --disable-addons
```

### 4. Document Test Scenarios

Create batch files for common test scenarios:

```batch theme={null}
:: 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:

```cmd theme={null}
findstr /I "error warning exception" %TEMP%\nvda.log
```

## Accessing User Documentation

If you need user documentation available in the Help menu:

```cmd theme={null}
scons source user_docs
runnvda.bat
```

<Note>
  Building user documentation is slower. Skip it for routine development unless you're specifically testing documentation features.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Building NVDA" icon="hammer" href="/development/building">
    Learn how to create binary builds and installers
  </Card>

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

  <Card title="GitHub Repository" icon="github" href="https://github.com/nvaccess/nvda">
    Browse the source code and submit contributions
  </Card>

  <Card title="Command Line Options" icon="terminal" href="https://download.nvaccess.org/documentation/userGuide.html#CommandLineOptions">
    Full list of command-line arguments
  </Card>
</CardGroup>