rules_jupyter

Bazel rules for running Jupyter notebooks and generating reports.

Setup

To use the rules, add the following to your MODULE.bazelrc.

bazel_dep(name = "rules_jupyter", version = "{version}")

Toolchains

These rules rely heavily on a jupyter_toolchain which will need to be setup.

In your MODULE.bazel, configure the convenience extensions. If Pandoc and Playwright browsers are available by some other means this can be skipped:

# Configure Pandoc (required for markdown reports)
jupyter = use_extension("@rules_jupyter//jupyter:extensions.bzl", "jupyter")
jupyter.pandoc(name = "pandoc")
use_repo(jupyter, "pandoc")

# Configure Playwright (required for WebPDF reports)
playwright = use_extension("@rules_jupyter//jupyter:extensions.bzl", "playwright")
playwright.toolchain(name = "playwright_toolchains", version = "1.57.0")
use_repo(playwright, "playwright_toolchains")
register_toolchains("@playwright_toolchains//:all")

Python dependencies will also be required for the toolchain. Rules such as rules_req_compile can be used for this.

In your BUILD.bazel:

load("@rules_jupyter//jupyter:jupyter_toolchain.bzl", "jupyter_toolchain")

jupyter_toolchain(
    name = "jupyter_toolchain",
    jupyter = "@pip_deps//jupyter",
    jupytext = "@pip_deps//jupytext",
    # Produced by rules_jupyter module extension.
    pandoc = "@pandoc",
    # Produced by rules_jupyter module extension.
    playwright_browsers_dir = "@rules_jupyter//playwright:current_browsers_dir",
)

toolchain(
    name = "jupyter_toolchain",
    toolchain = ":jupyter_toolchain",
    toolchain_type = "@rules_jupyter//jupyter:toolchain_type",
)

Register it in MODULE.bazel:

register_toolchains(
    "//:jupyter_toolchain",
)

Jupyter rules

Rules

• jupyter_lab
• jupyter_notebook
• jupyter_notebook_binary
• jupyter_notebook_test
• jupyter_report
• jupyter_toolchain

jupyter_lab

load("@rules_jupyter//jupyter:defs.bzl", "jupyter_lab")

jupyter_lab(name, data, app_settings, cwd_mode, env, env_inherit, execute, notebook, run_mode)

Launches a Jupyter Lab server for interactive notebook development.

This rule creates an executable target that, when run via bazel run, starts a Jupyter Lab server with the notebook's dependencies available in the virtualenv. By default, when a user opens the printed URL in their browser, all notebook cells are automatically executed — exactly as if the user clicked "Run All Cells" in Lab's Run menu.

Example:

jupyter_notebook(
    name = "my_notebook",
    src = "notebook.py",
    deps = ["@pip_deps//polars"],
)

jupyter_lab(
    name = "my_lab",
    notebook = ":my_notebook",
)

Then run: bazel run :my_lab

ATTRIBUTES

jupyter_notebook

load("@rules_jupyter//jupyter:defs.bzl", "jupyter_notebook")

jupyter_notebook(name, deps, src, data, kernel)

Compiles a Jupyter notebook from source and prepares it for execution.

This rule processes notebook source files and converts them to the standard .ipynb format. If the source is a .py file in Jupytext format (with # %% cell markers), it will be converted to .ipynb format. If the source is already a .ipynb file, it is used directly.

Example:

jupyter_notebook(
    name = "my_notebook",
    src = "notebook.py",  # or "notebook.ipynb"
    kernel = "python3",   # optional
    deps = ["@pip_deps//polars"],
    data = ["data.csv"],
)

ATTRIBUTES

jupyter_notebook_binary

load("@rules_jupyter//jupyter:defs.bzl", "jupyter_notebook_binary")

jupyter_notebook_binary(name, data, cwd_mode, env, env_inherit, notebook, out_dir, reports)

An executable rule that runs a Jupyter notebook and optionally generates reports.

Unlike jupyter_notebook_test, this rule creates an executable target for use with bazel run. Outputs (executed notebook and reports) are written to a configurable output directory, defaulting to the caller's working directory (BUILD_WORKING_DIRECTORY).

Example:

jupyter_notebook(
    name = "my_notebook",
    src = "notebook.py",
    deps = ["@pip_deps//polars"],
)

jupyter_notebook_binary(
    name = "run_notebook",
    notebook = ":my_notebook",
    reports = ["html"],
)

Then run: bazel run :run_notebook or bazel run :run_notebook -- --my-flag value

ATTRIBUTES

jupyter_notebook_test

load("@rules_jupyter//jupyter:defs.bzl", "jupyter_notebook_test")

jupyter_notebook_test(name, data, cwd_mode, env, env_inherit, notebook, reports)

A test rule that executes a Jupyter notebook and optionally generates reports. The test fails if any notebook cell raises an error.

ATTRIBUTES

jupyter_report

load("@rules_jupyter//jupyter:defs.bzl", "jupyter_report")

jupyter_report(name, data, args, cwd_mode, env, notebook, out_html, out_html_template_type,
               out_latex, out_latex_template_type, out_markdown, out_notebook, out_rst, out_webpdf)

Executes a Jupyter notebook and generates reports in various formats (HTML, Markdown, LaTeX, PDF, RST, WebPDF).

ATTRIBUTES

jupyter_toolchain

load("@rules_jupyter//jupyter:defs.bzl", "jupyter_toolchain")

jupyter_toolchain(name, cwd_mode, jupyter, jupytext, kernel, pandoc, playwright_browsers_dir,
                  playwright_ld_library_dir)

Defines a Jupyter toolchain that provides Jupyter, Jupytext, Pandoc, and Playwright browser support.

ATTRIBUTES