NVDA, the free and open source Screen Reader for Microsoft Windows
Python C++ C NSIS Makefile HTML
Switch branches/tags
release-2017.1 release-2017.1rc1 release-2016.4 release-2016.4rc2 release-2016.4rc1 release-2016.3 release-2016.3rc2 release-2016.3rc1 release-2016.2.1 release-2016.2 release-2016.2rc1 release-2016.1 release-2016.1rc1 release-2015.4 release-2015.4rc1 release-2015.3 release-2015.3rc1 release-2015.2 release-2015.2rc2 release-2015.2rc1 release-2015.1 release-2015.1rc1 release-2014.4 release-2014.4rc1 release-2014.3 release-2014.3rc3 release-2014.3rc2 release-2014.3rc1 release-2014.2 release-2014.2rc1 release-2014.1 release-2014.1rc4 release-2014.1rc3 release-2014.1rc2 release-2014.1rc1 release-2013.3 release-2013.3rc4 release-2013.3rc3 release-2013.3rc2 release-2013.3rc1 release-2013.2 release-2013.2rc2 release-2013.2rc1 release-2013.1.1 release-2013.1 release-2013.1rc2 release-2013.1rc1 release-2013.1beta2 release-2013.1beta1 release-2012.3.1 release-2012.3 release-2012.3rc1 release-2012.3beta3 release-2012.3beta2 release-2012.3beta1 release-2012.2.1 release-2012.2 release-2012.2rc2 release-2012.2rc1 release-2012.2beta2 release-2012.2beta1 release-2012.1 release-2012.1rc1 release-2012.1beta2 release-2012.1beta1 release-2011.3 release-2011.3rc1 release-2011.3beta1 release-2011.2 release-2011.2rc1 release-2011.2beta3 release-2011.2beta2 release-2011.2beta1 release-2011.1.1 release-2011.1.1rc1 release-2011.1 release-2011.1rc1 release-2011.1beta2 release-2011.1beta1 release-2010.2 release-2010.2rc1 release-2010.2beta2 release-2010.2beta1 release-2010.1 release-2010.1rc1 release-2010.1beta1 release-2009.1 release-2009.1rc1 release-2009.1beta1 release-0.6p3.2 release-0.6p3.1 release-0.6p3 release-0.6p2 release-0.6p1 release-0.5 release-0.5.next
Nothing to show
Failed to load latest commit information.
appveyor Upload appropriate debug symbols to Mozilla crash-stats for branch sn… Jan 30, 2017
extras/controllerClient Remove extras/NVDA CD, which is extremely outdated and no longer useful. Apr 30, 2014
include Update to pySerial 2.7. (PR #6854, issue #6845) Mar 29, 2017
launcher The NVDA launcher will no longer show a warning dialog when it can't … Jan 11, 2017
miscDeps @ 3efa98d Update to pySerial 2.7. (PR #6854, issue #6845) Mar 29, 2017
nvdaHelper Address code review comments. Apr 3, 2017
site_scons/site_tools Fixed building of developer documentation for NVDAHelper using "scons… Oct 5, 2016
source Split panes are now considered layout instead of content (PR #7049) Apr 25, 2017
tests Remove files accidentally committed in bddfab6. Apr 12, 2017
uninstaller Provide programmatic version information in all of our executables an… Sep 1, 2016
user_docs L10n updates for: zh_TW Apr 20, 2017
.gitattributes Added .gitattributes Nov 15, 2013
.gitignore Add initial unit testing framework. Mar 29, 2017
.gitmodules Update to pySerial 2.7. (PR #6854, issue #6845) Mar 29, 2017
appveyor.yml AppVeyor: Run automated tests. Mar 29, 2017
contributors.txt Update What's New and Contributors. Oct 5, 2016
copying.txt License: Add title. Nov 1, 2013
developerGuide.t2t Developer guide: correct link to the "Translating NVDA" page on Githu… Feb 15, 2017
keyCommandsDoc.py In the User Guide, when a %kc:setting command is used for a setting w… Mar 30, 2016
readme.md Initial unit testing framework and tests. (#7026) Apr 12, 2017
scons.bat Fix scons.bat failure when the NVDA source tree resides in a path con… Jul 18, 2016
scons.py Add scripts to allow scons to be run just by typing scons at the root… Dec 10, 2013
sconstruct Initial unit testing framework and tests. (#7026) Apr 12, 2017



NVDA is a free, open source screen reader for Microsoft Windows. It is developed by NV Access in collaboration with a global community of contributors. To learn more about NVDA or download a copy, visit the main NV Access website.

Key Project Links

Getting the Source Code

The NVDA project uses the Git version control system for its source code and documentation.

The NVDA Git repository is located at https://github.com/nvaccess/nvda.git. You can clone it with the following command, which will place files in a directory named nvda:

git clone --recursive https://github.com/nvaccess/nvda.git

The --recursive option is needed to retrieve various Git submodules we use.


The NVDA source depends on several other packages to run correctly.

Installed Dependencies

The following dependencies need to be installed on your system:

Git Submodules

Most of the dependencies are contained in Git submodules. If you didn't pass the --recursive option to git clone, you will need to run git submodule update --init. Whenever a required submodule commit changes (e.g. after git pull), you will need to run git submodule update. If you aren't sure, run git submodule update after every git pull, merge or checkout.

For reference, the following dependencies are included in Git submodules:

Other Dependencies

These dependencies are not included in Git submodules, but aren't needed by most people.

  • If you want to be able to use the Handy Tech braille display driver when running from source code, you will need to install the Handy Tech universal driver
  • To generate developer documentation for nvdaHelper: Doxygen Windows installer, version 1.7.3:

Preparing the Source Tree

Before you can run the NVDA source code, you must prepare the source tree. You do this by opening a command prompt, changing to the root of the NVDA source distribution and typing:

scons source

You should do this again whenever the version of comtypes changes or language files are added or changed. Note that if you want to access user documentation from the help menu while running the source version, you will also need to add user_docs to the commandline like so:

scons source user_docs

While simply testing or committing changes, it may be faster usually just doing scons source as user documentation will change each time the revision number changes.

Compiling NVDAHelper with Debugging Options

Among other things, preparing the source tree builds the NVDAHelper libraries.
If trying to debug nvdaHelper, You can control various debugging options with the nvdaHelperDebugFlags command line variable. It takes one or more of the following flags:

  • debugCRT: the libraries will be linked against the debug C runtime and assertions will be enabled. (By default, the normal CRT is used and assertions are disabled.)
  • RTC: runtime checks (stack corruption, uninitialized variables, etc.) will be enabled. (The default is no runtime checks.)
  • analyze: runs MSVC code analysis on all nvdaHelper code, holting on any warning. (default is no analysis).

The special keywords none and all can also be used in place of the individual flags.

An example follows that enables debug CRT and runtype checks

scons source nvdaHelperDebugFlags=debugCRT,RTC

Symbol pdb files are always produced when building, regardless of the debug flags. However, they are not included in the NVDA distribution. Instead, scons symbolsArchive will package them as a separate archive.

By default, builds also do not use any compiler optimizations. Please see the release keyword argument for what compiler optimizations it will enable.

Running the Source Code

To start NVDA from source code, run nvda.pyw located in the source directory. To view help on the arguments that NVDA will accept, use the -h or --help option. These arguments are also documented in the user guide. Since NVDA is a Windows application (rather than command line), it is best to run it with pythonw.exe. However, if during development you encounter an error early in the startup of NVDA, you can use python.exe which is likely to give more information about the error.

Building NVDA

A binary build of NVDA can be run on a system without Python and all of NVDA's other dependencies installed (as we do for snapshots and releases).

Binary archives and bundles can be created using scons from the root of the NVDA source distribution. To build any of the following, open a command prompt and change to this directory.

To make a non-archived binary build (equivalent to an extracted portable archive), type:

scons dist

The build will be created in the dist directory.

To create a launcher archive (one executable allowing for installation or portable dist generation), type:

scons launcher

The archive will be placed in the output directory.

To generate developer documentation, type:

scons devDocs

The developer docs will be placed in the devDocs folder in the output directory.

To generate developer documentation for nvdaHelper (not included in the devDocs target):

scons devDocs_nvdaHelper

The documentation will be placed in the devDocs\nvdaHelper folder in the output directory.

To generate an archive of debug symbols for the various dll/exe binaries, type:

scons symbolsArchive

The archive will be placed in the output directory.

To generate a gettext translation template (for translators), type:

scons pot

Optionally, the build can be customised by providing variables on the command line:

  • version: The version of this build.
  • release: Whether this is a release version.
    • This enables various C++ compiler optimizations such as /O2 and whole-program optimization.
    • It also instructs Python to generate optimized byte code.
  • publisher: The publisher of this build.
  • certFile: The certificate file with which to sign executables. The certificate must be in pfx format and contain the private key.
  • certPassword: The password for the private key in the signing certificate. If omitted, no password will be assumed.
  • certTimestampServer: The URL of the timestamping server to use to timestamp authenticode signatures. If omitted, signatures will not be timestamped.
  • outputDir: The directory where the final built archives and such will be placed.
  • targetArchitectures: The target architectures that NVDA should support. Possible values are all, x86 and x86_64. This should generally be left as the default.

For example, to build a launcher with a specific version, you might type:

scons launcher version=test1

Running Automated Tests

If you make a change to the NVDA code, you should run NVDA's automated tests. These tests help to ensure that code changes do not unintentionally break functionality that was previously working. Currently, NVDA has only one kind of automated testing: unit tests.

To run the unit tests, first change directory to the root of the NVDA source distribution as above. Then, run:

scons tests

To run only specific tests, specify them using the unitTests variable on the command line. The tests should be provided as a comma separated list. Each test should be specified as a Python module, class or method relative to the tests\unit directory. For example, to run only methods in the TestMove and TestSelection classes in the file tests\unit\test_cursorManager.py file, run this command:

scons tests unitTests=test_cursorManager.TestMove,test_cursorManager.TestSelection