> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nvaccess/nvda/llms.txt
> Use this file to discover all available pages before exploring further.

# NVDA Add-on Development Overview

> Introduction to creating add-ons for the NVDA screen reader

## What are NVDA Add-ons?

Add-ons allow you to customize and extend NVDA's functionality. They can:

* Add support for specific applications (App Modules)
* Implement new global commands (Global Plugins)
* Customize behavior of controls (NVDA Objects)
* Add speech synthesizers and braille display drivers
* Provide new functionality across the entire operating system

<Note>
  Add-ons are Python modules packaged with a manifest file and distributed as `.nvda-addon` files.
</Note>

## Types of Add-on Components

### App Modules

App modules provide application-specific support. They:

* Are loaded when a specific application is running
* Are named after the executable (e.g., `notepad.py` for notepad.exe)
* Can handle events and define scripts specific to that application
* Are automatically loaded and unloaded as the application starts and closes

[Learn more about App Modules →](/development/addons/app-modules)

### Global Plugins

Global plugins provide functionality across all applications. They:

* Are loaded when NVDA starts
* Can respond to events from any application
* Can implement global commands accessible anywhere
* Remain active until NVDA exits

[Learn more about Global Plugins →](/development/addons/global-plugins)

### Custom NVDA Objects

NVDA Objects represent individual controls and widgets. You can create custom NVDA Object classes to:

* Provide better accessibility for specific controls
* Customize how information is presented to users
* Add functionality to existing controls
* Implement text support for controls that don't natively support it

[Learn more about Custom NVDA Objects →](/development/addons/custom-nvda-objects)

## Add-on Structure

<CodeGroup>
  ```text Basic Structure theme={null}
  myAddon/
  ├── manifest.ini
  ├── appModules/
  │   └── myapp.py
  ├── globalPlugins/
  │   └── myplugin.py
  ├── locale/
  │   ├── en/
  │   └── es/
  └── doc/
      └── en/
          └── readme.md
  ```

  ```ini manifest.ini theme={null}
  name = myAddon
  summary = My NVDA Add-on
  author = Your Name
  version = 1.0.0
  minimumNVDAVersion = 2023.1.0
  lastTestedNVDAVersion = 2024.1.0
  url = https://github.com/yourusername/myaddon
  ```
</CodeGroup>

## Development Workflow

<Steps>
  <Step title="Set up the scratchpad directory">
    Enable the scratchpad directory in NVDA Settings > Advanced. This allows you to test code without creating full add-on packages.

    The scratchpad is located at: `%APPDATA%\nvda\scratchpad\`
  </Step>

  <Step title="Create your code">
    Place your Python files in the appropriate subdirectories:

    * `scratchpad/appModules/` for app modules
    * `scratchpad/globalPlugins/` for global plugins
  </Step>

  <Step title="Reload plugins">
    Use NVDA+Control+F3 or select Tools > Reload plugins to test your changes without restarting NVDA.
  </Step>

  <Step title="Package as an add-on">
    Once your code is working, create a proper add-on package with a manifest file for distribution.
  </Step>
</Steps>

## API Stability

The NVDA Add-on API consists of all NVDA Python objects, classes, and functions, excluding:

* Symbols prefixed with underscore (`_`) - these are private
* Transitive imports
* Pip packages (may be updated at any time)

<Warning>
  **Breaking changes** only occur in annual `.1` releases (e.g., 2026.1). Standard releases (2026.2, 2026.3) preserve API signatures but may add new features.
</Warning>

### API Release Cycle

* **Annual API-breaking release** (e.g., 2026.1): Signature-breaking changes are permitted
* **Standard releases** (e.g., 2026.2, 2026.3): Existing API signatures are preserved, new features may be added
* **Bug fixes and behavioral refinements**: Permitted in any release
* **Security improvements**: Take precedence over backward compatibility

## Key Resources

* [NVDA Add-on Store](https://addonstore.nvaccess.org/)
* [NVDA Add-on API Mailing List](https://groups.google.com/a/nvaccess.org/g/nvda-api)
* [Add-on Template Repository](https://github.com/nvaccess/AddonTemplate)
* [Submission Guide](https://github.com/nvaccess/addon-datastore/blob/master/docs/submitters/submissionGuide.md)
* [Community Add-ons](https://github.com/nvdaaddons)

## Python Requirements

NVDA add-ons are written in Python. You should be familiar with:

* Python syntax and basic concepts
* Object-oriented programming
* Python modules and packages
* Event-driven programming

<Note>
  NVDA uses a specific version of Python. Check the [Developer Guide](https://download.nvaccess.org/documentation/developerGuide.html) for the current version.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create an App Module" icon="window" href="/development/addons/app-modules">
    Add application-specific functionality
  </Card>

  <Card title="Build a Global Plugin" icon="globe" href="/development/addons/global-plugins">
    Implement system-wide features
  </Card>

  <Card title="API Reference" icon="book" href="/development/addons/api-reference">
    Browse the complete API documentation
  </Card>

  <Card title="Distribution Guide" icon="box" href="/development/addons/distribution">
    Package and distribute your add-on
  </Card>
</CardGroup>