Plugins — Pygments

- Home
- Languages
- Styles
- FAQ
- Get it
- Docs

# Plugins

If you want to extend Pygments without hacking the sources, you can use package entry points to add new lexers, formatters, styles or filters as if they were in the Pygments core.

The idea is to create a Python package, declare how extends Pygments, and install it.

This will allow you to use your custom lexers/… with the `pygmentize` command. They will also be found by the lookup functions (`lexers.get_lexer_by_name` et al.), which makes them available to tools such as Sphinx, mkdocs, …

## Plugin discovery

At runtime, discovering plugins is preferentially done using Python’s standard library module importlib.metadata, available in Python 3.8 and higher. In earlier Python versions, Pygments attempts to use the importlib_metadata backport, if available. If not available, a fallback is attempted on the older pkg_resources module. Finally, if `pkg_resources` is not available, no plugins will be loaded at all. Note that `pkg_resources` is distributed with setuptools, and thus available on most Python environments. However, `pkg_resources` is considerably slower than `importlib.metadata` or its `importlib_metadata` backport. For this reason, if you run Pygments under Python older than 3.8, it is recommended to install `importlib-metadata`. Pygments defines a `plugins` packaging extra, so you can ensure it is installed with best plugin support (i.e., that `importlib-metadata` is also installed in case you are running Python earlier than 3.8) by specifying `pygments[plugins]` as the requirement, for example, with `pip`:

    $ python -m pip install --user pygments[plugins]

## Defining plugins through entry points

We have created a repository with a project template for defining your own plugins. It is available at

https://github.com/pygments/pygments-plugin-scaffolding

## Extending The Core

If you have written a Pygments plugin that is open source, please inform us about that. There is a high chance that we’ll add it to the Pygments distribution.