Defining plugins

bilby allows for additional customizations/extra features via plugins. This allows users to add new functionality without the need to modify the main bilby codebase, for example to add a new sampler.

To make your plugins discoverable to bilby, you need to specify a plugin group (which bilby knows to search for), a name for the plugin, and the python path to your function/class within your package metadata, see here for details. For example, if you have a package called mypackage and you wish to add a plugin called my_awesome_plugin within the group bilby.plugin, you would specify the following in your pyproject.toml file:

my_awesome_plugin = "mypackage.plugin"

Currently bilby allows for the following plugin groups:

  • "bilby.samplers": group for adding samplers to bilby. See Sampler plugins for more details.

Sampler plugins

Sampler plugins can specified via the "bilby.samplers" group and these are automatically added to the ‘known’ samplers in bilby. This allows users to add support for new samplers without having to modify the core bilby codebase. Sampler plugins should implement a sampler class that in inherits from one of the following classes:

We provide a template for creating sampler plugins on GitHub.


When implementing a new sampler plugin, please avoid using a generic name for the plugin (e.g. ‘nest’, ‘mcmc’) as this may lead to naming conflicts.

Sampler plugin library

This is a list of known sampler plugins. if you don’t see your plugin listed here, we encourage you to open a merge request to add it.

  • This could be your sampler

Bilby-native samplers

Some samplers are implemented directly in bilby and these are avertised under two possible names:

  • bilby.<sampler name>: always available, indicates the sampler is implemented in bilby,

  • <sampler name>: only refers to the native bilby implementation if an external plugin does not already provide this sampler.

This allows for an external plugin to provide a sampler without introducing namespace conflicts.

Information for bilby developers

Using plugins within bilby

Within bilby, plugins are discovered with the bilby.core.utils.get_entry_points() function, and can be used throughout the bilby infrastructure.

Adding a new plugin group

If you want to add support for a new plugin group, please open an issue to discuss the details with other developers.