Skip to main content
Thank you for your interest in contributing to NVDA! The NVDA project welcomes contributions from developers around the world. Whether you’re fixing bugs, adding features, or improving documentation, your help is valuable.
Please read and abide by the Citizen and Contributor Code of Conduct while participating in this project.

​
Before You Start

The NVDA project is guided by a product vision statement and set of principles. Always consider the vision and principles when planning features and prioritizing work.

​
Finding Issues to Work On

If you’re new to the project or looking for ways to help, check out:

​
Guidelines

​
Discuss Before You Code

For anything other than minor bug fixes, please comment on an existing issue or create a new issue before starting to code.
  • Unrelated changes should be addressed in separate issues
  • Include information about:
    • Use cases
    • Design considerations
    • User experience implications
  • Wait for acceptance of your proposal before coding
    • A triaged label indicates an issue is ready for a fix
    • Focus on higher priority issues (p1-p3) over lower priority ones (p4-p5)
  • Consider starting a GitHub discussion or mailing list topic to gauge interest
We very likely will not accept changes that are not discussed first. If in doubt, use an issue to discuss your ideas before submitting code.

​
Minor Changes Exception

You can create a pull request directly for minor/trivial changes that don’t require design or implementation discussion:
  • Typo fixes
  • Obvious coding errors
  • Simple synthesizer or braille display drivers
This should be fairly rare.

​
Translation Issues

Issues with translations should be reported to the NVDA Translators list.

​
Contribution Process

1

Set up your development environment

Set up your development environment or use GitHub Actions to build NVDA for you by following the CI/CD README.
2

Ensure the issue is triaged

Make sure the issue you plan to fix has been triaged and has a priority assigned.
3

Create a branch

Create a branch for your contribution based on the latest commit in the official master branch. This helps reduce merge conflicts.
4

Build and test

5

Run pre-submission checks

Before opening your pull request, run:
rununittests.bat    # Run unit tests
runlint.bat         # Check code style
runcheckpot.bat     # Check translatable strings
runlicensecheck.bat # Check dependency licenses
All tests must pass before submission.
6

Update documentation

If you’re adding a feature or changing something noticeable to users:
  • Update the User Guide
  • Document new commands, drivers, settings, dialogs, etc.
  • Follow the User Guide standards
7

Create a change log entry

Add an entry to the changes.md file in this format:
### New Features

* Added a command to announce useful thing. (#1234, #4321, @myGitHub)

### Changes

* Old command now also uses new useful command. (#1234)
Available sections:
  • New features
  • Changes
  • Bug fixes
  • Changes for developers
Change log entries are not required for changes with no/minor user impact or no developer impact.
8

Create a pull request

Fill out the Pull Request template including:
  • Link to issue number
  • Summary of the issue
  • Description of user-facing changes
  • Description of developer-facing changes
  • Development approach
  • Testing strategy
  • Known issues
Important:
  • Enable “Allow edits from maintainers” (default for new PRs)
  • Use draft PRs for early feedback
  • Mark as “ready for review” when you want code review
  • Consider targeting beta or rc for bugs in the current release cycle
9

CI/CD checks

Every time you push a commit:
  • pre-commit.ci applies linting fixes automatically
    • Re-run with comment: pre-commit.ci run
    • Skip with [skip ci] in commit message
  • GitHub Actions builds NVDA and creates artifacts for testing
  • System tests run automatically
  • Security checks verify code safety
Review any failures. Sometimes system tests fail unexpectedly - if you believe it’s unrelated, note it in the PR.
10

Participate in code review

  • Answer questions from reviewers
  • Discuss and implement suggested changes
  • Be proactive to speed up the review process
  • CoPilot AI may review your code - engage with helpful comments and explain why you’re ignoring others
When approved, your PR will be merged and included in the next alpha build.
11

Monitor feedback

After merging, watch for feedback from alpha users and testers. You may need to follow up to address bugs or missed use-cases.

​
Code Style

Please follow the coding standards documented separately. Key points:
  • Follow PEP 8 except where it contradicts NVDA-specific guidance
  • Use tabs for indentation, not spaces
  • Include type hints for all new code
  • Add docstrings for public functions and classes
  • Use descriptive names for identifiers
The Ruff linter enforces Python code style automatically.

​
Technical Design

Review the technical design overview to understand NVDA’s architecture. Refer to the guide on creating or updating copyright headers.

​
Ways to Contribute

Beyond code contributions, you can help NVDA in many ways:

​
Getting Help

If you need assistance:
The NVDA community is welcoming and supportive. Don’t hesitate to ask questions!

Build docs developers (and LLMs) love

Get started for freeTalk to us