Skip to content

Plugins

datalab's plugin system is under active development, as is this documentation page. The most mature plugin type are custom application data blocks, a template repository for which can be found at datalab-org/datalab-app-plugin-template (see more below).

datalab supports plugins that extend the server with new functionality. Some self-declared plugins can be found via the datalab-plugin topic on GitHub, in lieu of a formal registry at this time. Plugins can also be kept private and installed from e.g., a private git repository, or a local path on the host, using the same installation described below.

Only install plugins you trust

Plugins are installed into the same Python environment as the datalab server and run with full server privileges. Only install plugins from sources you trust.

What a plugin is

At present, a datalab plugin is a Python package that registers one or more data block classes via a Python entry point. Data blocks ingest a file (or set of files) attached to an item and render an interactive view of the parsed data, e.g. an NMR spectrum, an electrochemistry cycler trace, or an XRD pattern. datalab discovers them at server startup by enumerating the relevant entry point group, with no changes required to the core code.

Additional plugin types: custom item types, ingestion hooks, and webapp components are planned in the future (see roadmap.md); please reach out if you have a specific use case.

Writing a plugin

The recommended starting point is the Copier template at datalab-org/datalab-app-plugin-template, which scaffolds a minimal data block plugin together with the packaging boilerplate (entry point declaration, test scaffolding, and a working pyproject.toml). Rather than forking the repository, you should use it directly with Copier to generate a new plugin repository; see the README in the datalab-org/datalab-app-plugin-template repository for full instructions.

Installing plugins

Plugins are declared in a plugins.toml file at the root of the repository (alongside pydatalab/ and webapp/). The format mirrors the relevant fragments of pyproject.toml, and a generated JSON Schema describing the expected structure is checked in at pydatalab/schemas/plugin_config.json:

# plugins.toml (at the repository root)
dependencies = [
    "datalab-app-plugin-insitu",
    "my-local-plugin",
]

[tool.uv.sources]
# Pin to a specific git ref:
datalab-app-plugin-insitu = { git = "https://github.com/datalab-org/datalab-app-plugin-insitu.git", rev = "v0.4.1" }
# Or point at a local checkout (paths are resolved relative to plugins.toml itself):
my-local-plugin = { path = "../my-local-plugin", editable = true }

To install datalab together with the declared plugins:

cd pydatalab
uv run invoke dev.install

This task:

  1. Merges plugins.toml into a copy of pyproject.toml under ./build/ (as a plugins optional-dependency group, plus any [tool.uv.sources] entries).
  2. Regenerates ./build/uv.lock so plugin versions are locked alongside the core deps.
  3. Runs uv sync --all-extras --active --project ./build to install everything into the currently active datalab virtual environment.

Pass --no-dev to skip dev dependencies (used by the production Docker build).

If no plugins.toml is present, the task falls back to installing the base pyproject.toml — so it is safe to run unconditionally.

To revert to the locked core dependencies without any plugins, run:

uv sync --all-extras --dev

The same invoke dev.install task is used by the production Docker image (.docker/server/Dockerfile): a plugins.toml at the repository root is picked up automatically at build time, so plugins can be baked into a custom image without modifying the Dockerfile itself. It will also be invoked from the datalab Ansible role to provision plugins on a deployed server when a plugins.toml is provided; see the role documentation for details.