nvda-addon-kit

Scaffold, build, translate and install NVDA add-ons from a single addon.toml.

This is the successor to the SCons-based addonTemplate. Instead of forking a template repository and editing buildVars.py, you install a tool:

pip install nvda-addon-kit
nvaddon init myAddon
cd myAddon
nvaddon build

Tool can also be run as a module:

py -3.13 -m nvaddon init myAddon

Commands

Command	Does
nvaddon init [dir]	Create a new add-on, interactively or from flags
nvaddon build	Produce <name>-<version>.nvda-addon
nvaddon install	Build, then hand the add-on to NVDA to install
nvaddon install --link	Link the working tree into NVDA's add-ons directory for development
nvaddon pot	Generate <name>.pot from Python sources and addon.toml
nvaddon locale-add <lang>…	Start a new translation
nvaddon locale-update	Merge new messages into every existing translation
nvaddon locale-compile	Compile .po files and translated manifests
nvaddon check	Validate addon.toml against add-on store rules
nvaddon clean	Remove generated build outputs
nvaddon migrate	Modernise a SCons-era add-on: config, build machinery, CI, pyproject
nvaddon release <version>	Set version and channel, commit, tag v<version>-<channel>, and push
nvaddon crowdin	Sync translations with Crowdin

Run nvaddon <command> --help for the flags each one accepts.

Releasing

nvaddon release 1.2.0 --channel beta

This writes the version and channel into addon.toml, commits, creates an annotated tag and pushes the commit and tag to the server. Use --no-push to stop before publishing.

It shows what it is about to do and waits for confirmation:

About to release:

  current version  5.1.0 (stable)
  release version  5.2.0 (beta)
  tag              v5.2.0-beta
  push             yes

Release? [Y/n]:

Pass -y to skip the prompt. Everything that could refuse the release is checked before you are asked, so you are never invited to approve something that cannot succeed.

The bundled release.yml workflow runs on every push and pull request. Without a tag it uploads the add-on and the .pot as artifacts On a tag it publishes both as assets of a GitHub release, and then submits to the add-on store if autoSubmit is true in addon.toml. Submission needs a USER_TOKEN secret. See Submit NVDA Addon github action for more details.

addon.toml

[addon]
name = "myAddon"
# Translators: Summary/title for this add-on, shown on install and in the add-on store.
summary = "Add-on user visible name"
# Translators: Long description shown for this add-on in the add-on store.
description = """Description for the add-on.
It can span multiple lines."""
version = "1.0.0"
author = "Name <name@domain.com>"
minimumNVDAVersion = "2024.1"
lastTestedNVDAVersion = "2025.3"

[build]
pythonSources = ["addon/globalPlugins/**/*.py"]

[l10n]
baseLanguage = "en"

The comment above a translatable key becomes that string's translator note in the generated .pot, exactly as # Translators: comments in buildVars.py did:

#. Translators: Summary/title for this add-on, shown on install and in the add-on store.
#: addon.toml:3
msgid "Add-on user visible name"
msgstr ""

Migrating an existing add-on

cd myExistingAddon
pip install nvda-addon-kit
nvaddon migrate
nvaddon check
nvaddon build

migrate --apply removes buildVars.py, sconstruct and site_scons/ for you. It refuses to run on a dirty working tree, so git diff shows exactly what changed.

Licence

GNU General Public License version 2 or later. See COPYING.txt.