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

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.