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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nvda_addon_kit-0.3.1.tar.gz (59.6 kB view details)

Uploaded Sep 5, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

nvda_addon_kit-0.3.1-py3-none-any.whl (81.7 kB view details)

Uploaded Sep 5, 2026 Python 3

File details

Details for the file nvda_addon_kit-0.3.1.tar.gz.

File metadata

Download URL: nvda_addon_kit-0.3.1.tar.gz
Upload date: Sep 5, 2026
Size: 59.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for nvda_addon_kit-0.3.1.tar.gz
Algorithm	Hash digest
SHA256	`e567330b4cbe4dcd86e54005179ff5199b340e8b30005a83099057103e749389`
MD5	`69331b416184f9ab9679adcf669f8b40`
BLAKE2b-256	`1d1a4c5f8c32ba4b79e17c1109888f3f288885041420695451fdb105d1f8d818`

See more details on using hashes here.

Provenance

The following attestation bundles were made for nvda_addon_kit-0.3.1.tar.gz:

Publisher: release.yml on addonFactory/NVDAAddonKit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: nvda_addon_kit-0.3.1.tar.gz
- Subject digest: e567330b4cbe4dcd86e54005179ff5199b340e8b30005a83099057103e749389
- Sigstore transparency entry: 2728811790
- Sigstore integration time: Sep 5, 2026
Source repository:
- Permalink: addonFactory/NVDAAddonKit@c92c416e4d557950d3a5d7e46c41ba38a1dc6e84
- Branch / Tag: refs/tags/v0.3.1
- Owner: https://github.com/addonFactory
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@c92c416e4d557950d3a5d7e46c41ba38a1dc6e84
- Trigger Event: push