Beets plugins are Python modules or packages that extend the core functionality of beets. The plugin system is designed to be flexible, allowing developers to add virtually any type of features to beets.

For instance you can create plugins that add new commands to the command-line interface, listen for events in the beets lifecycle or extend the autotagger with new metadata sources.

Basic Plugin Setup#

A beets plugin is just a Python module or package inside the beetsplug namespace [1] package. To create the basic plugin layout, create a directory called beetsplug and add either your plugin module:

beetsplug/
└── myawesomeplugin.py

or your plugin subpackage

beetsplug/
└── myawesomeplugin/
    ├── __init__.py
    └── myawesomeplugin.py

Attention

You do not need to add an __init__.py file to the beetsplug directory. Python treats your plugin as a namespace package automatically, thus we do not depend on pkgutil-based setup in the __init__.py file anymore.

The meat of your plugin goes in myawesomeplugin.py. Every plugin has to extend the beets.plugins.BeetsPlugin abstract base class [2] . For instance, a minimal plugin without any functionality would look like this:

# beetsplug/myawesomeplugin.py
from beets.plugins import BeetsPlugin


class MyAwesomePlugin(BeetsPlugin):
    pass

To use your new plugin, you need to package [3] your plugin and install it into your beets (virtual) environment. To enable your plugin, add it it to the beets configuration

# config.yaml
plugins:
  - myawesomeplugin

and you’re good to go!

More information#

For more information on writing plugins, feel free to check out the following resources: