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

# Development Environment Setup

> Complete guide to setting up your NVDA development environment on Windows

## Prerequisites

Before setting up NVDA development, ensure you have:

* Windows 10 (Version 22H2) or Windows 11
* Administrator access for installing development tools
* At least 10 GB of free disk space
* Internet connection for downloading dependencies

## Getting the Source Code

The NVDA project uses Git for version control. The repository is hosted on GitHub.

### Fork and Clone

If you plan to contribute to NVDA, start by forking the repository:

<Steps>
  <Step title="Fork the repository">
    Visit [https://github.com/nvaccess/nvda](https://github.com/nvaccess/nvda) and click the Fork button to create a copy in your GitHub account
  </Step>

  <Step title="Clone with submodules">
    Clone your fork with the `--recursive` flag to fetch all required submodules:

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

    <Warning>
      The `--recursive` flag is essential. Without it, you'll be missing critical dependencies contained in Git submodules.
    </Warning>
  </Step>

  <Step title="Navigate to the directory">
    ```bash theme={null}
    cd nvda
    ```
  </Step>
</Steps>

### Keeping Your Fork in Sync

When you fork the repository, GitHub creates a copy of the master branch. However, this branch won't automatically update when the NV Access master branch is updated.

To keep your work based on the latest commits:

```bash theme={null}
# Add a remote for the NV Access repository
git remote add nvaccess https://github.com/nvaccess/nvda.git

# Fetch the NV Access branches
git fetch nvaccess

# Switch to the local master branch
git checkout master

# Set the local master to use the NV Access master as its upstream
git branch -u nvaccess/master

# Update the local master
git pull
```

<Note>
  This configuration ensures your master branch stays synchronized with the official NVDA repository.
</Note>

### Managing Git Submodules

If you didn't use `--recursive` when cloning, initialize submodules manually:

```bash theme={null}
git submodule update --init
```

After any `git pull`, `merge`, or `checkout`, update submodules:

```bash theme={null}
git submodule update
```

<Tip>
  Run `git submodule update` after every pull to ensure submodules are current.
</Tip>

## Installing Required Dependencies

### Python 3.13.12

NVDA requires a specific version of Python:

<Steps>
  <Step title="Check the required version">
    The exact version is specified in `.python-versions` in the repository root. As of now, it's **Python 3.13.12, 64-bit**.
  </Step>

  <Step title="Download Python">
    Download Python 3.13.12 from [python.org](https://www.python.org/downloads/)
  </Step>

  <Step title="Install Python">
    Run the installer and ensure you:

    * Select the 64-bit version
    * Add Python to PATH
    * Install for all users (recommended)
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    python --version
    ```

    Should output: `Python 3.13.12`
  </Step>
</Steps>

<Warning>
  You must use Python 3.13.12 specifically. NVDA requires Python >= 3.13 and \< 3.14.
</Warning>

### uv Package Manager

NVDA uses [uv](https://docs.astral.sh/uv/) as its package and project manager.

```bash theme={null}
# Install uv
pip install uv
```

### Microsoft Visual Studio

Visual Studio is required for compiling C++ components.

#### Choose Your Edition

<CardGroup cols={2}>
  <Card title="Build Tools" icon="hammer">
    Minimal installation for command-line builds

    [Download Build Tools](https://aka.ms/vs/17/release/vs_BuildTools.exe)
  </Card>

  <Card title="Community Edition" icon="windows">
    Full IDE with debugging capabilities

    [Download Community](https://aka.ms/vs/17/release/vs_Community.exe)
  </Card>
</CardGroup>

<Note>
  To replicate the production build environment, use the [version of Visual Studio 2022 that GitHub Actions is using](https://github.com/actions/runner-images/tree/main/images/windows).
</Note>

#### Required Components

During installation, you must include specific components:

<Accordion title="Automatic Installation (Recommended)">
  Use NVDA's `.vsconfig` file for automatic component selection:

  1. Run the Visual Studio Installer
  2. Click "Import configuration"
  3. Select `.vsconfig` from the NVDA repository root
  4. The installer will automatically select all required components

  [Learn more about importing VS configurations](https://learn.microsoft.com/en-us/visualstudio/install/import-export-installation-configurations?view=vs-2022#import-a-configuration)
</Accordion>

<Accordion title="Manual Installation">
  If installing manually, select these components:

  **Workloads Tab:**

  * Desktop development with C++
    * Ensure "C++ Clang tools for Windows" is included in optional components

  **Individual Components Tab:**

  * Windows 11 SDK (10.0.26100.x)
  * MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools
  * MSVC v143 - VS 2022 C++ x64/x86 build tools
  * C++ ATL for v143 build tools (x86 & x64)
  * C++ ATL for v143 build tools (ARM64/ARM64EC)
</Accordion>

<Warning>
  Preview or Insiders versions of Visual Studio are **not supported**. Use stable releases only.
</Warning>

## Git Submodule Dependencies

NVDA includes several dependencies as Git submodules:

### Runtime Dependencies

* **eSpeak NG** (commit `b0b605c8a80f76c4c19e18033c6780c3cc4afc5b`) - Speech synthesis
* **Sonic** (commit `d2cdb40fbdc82b464be364a50b34e8dd82b6c80a`) - Audio speed adjustment
* **IAccessible2** (commit `c9ae003d9c85eb707716928de97e055f5b77189c`) - Accessibility API
* **liblouis** (version 3.36.0) - Braille translation
* **Unicode CLDR** (version 48.0) - Locale data
* **Microsoft Detours** (commit `9764cebcb1a75940e68fa83d6730ffaf0f669401`) - API hooking
* **Windows Implementation Library (WIL)** (commit `7cf41936c5b4ab79daf0d9437211380dc69fa958`)
* **Java Access Bridge 64-bit** (Zulu 17.0.16+8)
* **Adobe Acrobat accessibility interface** (version XI)
* **brlapi** (version 0.8.7+) - Braille device communication
* **Nullsoft Install System** (version 3.11) - Installer creation

### Build Time Dependencies

Included in the `miscDeps` submodule:

* **xgettext** and **msgfmt** from GNU gettext - Translation tools

## Python Dependencies

NVDA depends on numerous Python packages specified in `pyproject.toml`. The build system automatically manages these dependencies using uv.

### Key Python Packages

**Runtime:**

* comtypes 1.4.13
* wxPython 4.2.4
* pywin32 311
* cryptography 46.0.5
* pyserial 3.5
* requests 2.32.5

**Build:**

* SCons 4.10.1
* py2exe 0.14.0.0
* setuptools \~80.10.2

**Development:**

* ruff 0.14.5 (linter and formatter)
* pyright 1.1.407 (type checker)
* pre-commit 4.2.0 (git hooks)

<Note>
  All Python dependencies are installed into an isolated virtual environment within the repository. They won't affect your system-wide Python installation.
</Note>

## Visual Studio Code (Optional)

If you use VS Code, NVDA provides a preconfigured workspace:

The `.vscode` submodule contains [prepopulated workspace configuration](https://github.com/nvaccess/vscode-nvda/).

### Disable VS Code Configuration

If you prefer not to use the preconfigured workspace:

```bash theme={null}
git submodule deinit .vscode
```

### Re-enable Later

```bash theme={null}
git submodule init .vscode
```

## Optional Dependencies

### Doxygen (Developer Documentation)

Only needed if you want to generate nvdaHelper C++ documentation:

* Download [Doxygen Windows installer](http://www.doxygen.nl/download.html), version 1.8.15

## Verifying Your Setup

After installing all dependencies, verify your setup:

```bash theme={null}
# Check Python version
python --version

# Check if uv is installed
uv --version

# Verify Git submodules are initialized
git submodule status

# Check Visual Studio installation
where cl.exe
```

All commands should complete without errors.

## Next Steps

<CardGroup cols={2}>
  <Card title="Building NVDA" icon="hammer" href="/development/building">
    Learn how to build NVDA from source
  </Card>

  <Card title="Running from Source" icon="play" href="/development/running-from-source">
    Run NVDA directly without building installers
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Submodules not initialized">
    If you see empty directories in `include/` or `miscDeps/`:

    ```bash theme={null}
    git submodule update --init --recursive
    ```
  </Accordion>

  <Accordion title="Python version mismatch">
    Ensure you're using Python 3.13.12 exactly:

    ```bash theme={null}
    python --version
    ```

    If incorrect, uninstall other Python versions or use virtual environments.
  </Accordion>

  <Accordion title="Visual Studio components missing">
    Re-run the Visual Studio Installer and import the `.vsconfig` file from the NVDA repository root.
  </Accordion>

  <Accordion title="Build tools not found">
    Ensure Visual Studio's build tools are in your PATH:

    ```bash theme={null}
    "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64
    ```
  </Accordion>
</AccordionGroup>