Plugins are a feature in Snakebids that enables you to add custom functionality to your Snakebids application after parsing CLI arguments but before invoking Snakemake. For example, you can use a plugin to perform BIDS validation of your Snakebids app’s input, which ensures your app is only executed if the input dataset is valid. You can either use those that are distributed with Snakebids (see Using plugins) or create your own plugins (see Creating plugins).


For a full list of plugins distributed with Snakebids, see the Plugins reference page.

Using plugins#

To add one or more plugins to your SnakeBidsApp, pass them to the SnakeBidsApp constructor via the plugins parameter. Your plugin will have access to CLI parameters (after they’ve been parsed) via their names in SnakeBidsApp.config. Any modifications to that config dictionary made by the plugin will be carried forward into the workflow.

As an example, the distributed BidsValidator plugin can be used to run the BIDS Validator on the input directory like so:

import subprocess

from import SnakeBidsApp
from snakebids.plugins.validator import BidsValidator


Creating plugins#

A plugin is a function or callable class that accepts a SnakeBidsApp as input and returns a modified SnakeBidsApp or None.

As an example, a simplified version of the bids-validator plugin that runs the BIDS Validator could be defined as follows:

import subprocess 

from import SnakeBidsApp
from snakebids.exceptions import SnakeBidsPluginError

class BidsValidator:
    """Perform BIDS validation of dataset

        Snakebids application to be run

    def __call__(self, app: SnakeBidsApp) -> None:
        # Skip bids validation
        if app.config["plugins.validator.skip"]:

  ["bids-validator", app.config["bids_dir"]], check=True)
        except subprocess.CalledProcessError as err:
            raise InvalidBidsError from err

class InvalidBidsError(SnakebidsPluginError):
    """Error raised if input BIDS dataset is invalid, 
    inheriting from SnakebidsPluginError.


When adding plugin-specific parameters to the config dictionary, it is recommended to use namespaced keys (e.g. plugins.validator.skip). This will help ensure plugin-specific parameters do not conflict with other parameters already defined in the dictionary or by other plugins.

A plugin can be used to implement any logic that can be handled by a Python function. In the above example, you may also want to add some logic to check if the BIDS Validator is installed and pass along a custom error message if it is not. Created plugins can then be used within a Snakebids workflow, similar to the example provided in Using plugins section. Prospective plugin developers can take a look at the source of the snakebids.plugins module for examples.


When creating a custom error for your Snakebids plugin, it is recommended to inherit from SnakebidsPluginError such that errors will be recognized as a plugin error.