Hatch Jupyter Builder Plugin

0.9.1 · active · verified Thu Apr 16

Hatch Jupyter Builder is a Hatch plugin designed to streamline the building and packaging of Jupyter-related projects, such as JupyterLab extensions, JupyterLite applications, and kernels. It integrates frontend build steps (e.g., npm/yarn) directly into the Python packaging process, ensuring consistent builds and proper inclusion of static assets. The current version is 0.9.1, with a release cadence of regular patch and minor updates addressing bug fixes and enhancements.

Common errors

```
ERROR: No such builder: jupyter
```
cause The `hatch-jupyter-builder` plugin is either not installed or not listed in the `build-system.requires` array in your `pyproject.toml`.

fix Ensure you have installed the plugin (`pip install hatch-jupyter-builder`) and added `"hatch-jupyter-builder"` to `build-system.requires` in your `pyproject.toml`.
```
ModuleNotFoundError: No module named 'hatch'
```
cause The core `hatch` build tool is not installed in your environment.

fix Install Hatch: `pip install hatch`.
```
[ERROR] Target 'path/to/expected/file.js' was not found after build.
```
cause A file specified in `ensured-targets` within `[tool.hatch.build.hooks.jupyter]` was not found after the frontend build commands completed. This indicates either the build failed, the file was not generated, or the path in `ensured-targets` is incorrect.

fix Check the output of your `npm` (or `yarn`) commands for errors. Verify that the `build-dir` and `ensured-targets` paths in your `pyproject.toml` correctly point to the location where the frontend assets are generated relative to the project root.

Warnings

breaking When migrating from older build systems like `jupyter_packaging` or manual `setup.py` scripts, `hatch-jupyter-builder` requires a complete re-evaluation of your `pyproject.toml` configuration. Direct translation of options is not always straightforward, especially for build hooks and asset inclusion.
Fix: Refer to the `hatch-jupyter-builder` official documentation and examples for the equivalent `pyproject.toml` configuration tailored to your project's specific build requirements.
gotcha If your frontend assets are not being built or included in the final package, ensure that `builder = 'jupyter'` is correctly specified under `[tool.hatch.build.targets.wheel]` (and `sdist` if desired) and that `[tool.hatch.build.hooks.jupyter]` contains the correct `build-dir`, `npm` (or `yarn`) commands, and `ensured-targets` paths.
Fix: Carefully review your `pyproject.toml` file, paying close attention to the `[tool.hatch.build.hooks.jupyter]` section. Verify that all paths (e.g., `build-dir`, `ensured-targets`) are correct relative to your `pyproject.toml` and that the specified frontend commands execute successfully in isolation.
gotcha The `optional-editable-build` feature, which can significantly improve local development workflows by avoiding unnecessary frontend rebuilds, was introduced in `hatch-jupyter-builder` version 0.8.0. Projects attempting to use this option with older plugin versions will encounter build failures.
Fix: Upgrade `hatch-jupyter-builder` to version 0.8.0 or newer to utilize `optional-editable-build`. If upgrading is not possible, remove this option from your `pyproject.toml` configuration.

Install

pip install hatch hatch-jupyter-builder Install Hatch and the plugin

Imports

Configuration
```
This plugin is primarily configured via `pyproject.toml`, not typically imported directly in Python code.
```
Users enable and configure `hatch-jupyter-builder` by adding it to `build-system.requires` and defining options under `[tool.hatch.build.targets.wheel]` and `[tool.hatch.build.hooks.jupyter]`.

Quickstart

This `pyproject.toml` snippet demonstrates how to configure `hatch-jupyter-builder` for a project that includes a JavaScript/TypeScript frontend. It enables the 'jupyter' builder for wheel targets and defines a `jupyter` build hook to execute `npm` commands within a specified `build-dir`.

# pyproject.toml
[build-system]
requires = ["hatchling>=1.5", "hatch-jupyter-builder>=0.9.0"]
build-backend = "hatchling.build"

[project]
name = "my-jupyter-pkg"
version = "0.1.0"
requires-python = ">=3.8"
description = "A Jupyter package built with hatch-jupyter-builder."

[tool.hatch.build.targets.wheel]
builder = "jupyter"

[tool.hatch.build.hooks.jupyter]
# Directory containing package.json for frontend (relative to pyproject.toml)
build-dir = "js"
# Commands to run for frontend build
npm = ["install", "run", "build"]
# Files that must exist after the frontend build to indicate success
# ensured-targets = [
#     "my_jupyter_pkg/static/main.js"
# ]

view raw JSON →