Jupyter Blog - Darshan Kr. Paudyal

Announcing jupyter-builder: A Standalone Build System for JupyterLab Extensions

2026-06-19T13:11:00+00:00

We’re excited to announce the first stable release of jupyter-builder on PyPI and @jupyter/builder on npm. A standalone, configurable build system for JupyterLab and its extensions.

If you build or maintain a JupyterLab extension, this release is for you.

Motivation

For a long time, building a JupyterLab extension has meant installing all of JupyterLab. Take a look at any extension’s build dependencies and you’ll see jupyterlab listed there, not because the extension needs JupyterLab at runtime to be built, but because the build tooling lives inside the JupyterLab repository. The builder/ folder, the jlpm command, the helper scripts, they’re all coupled to the JupyterLab core.

This setup has caused real friction over the years:

Linux packagers have repeatedly raised concerns about the circular dependency where extensions like jupyterlab_pygments need jupyterlab to build, but jupyterlab ships with those extensions. It’s a chicken-and-egg problem that makes packaging painful.
Extension authors have to update their build system every time they update to a new JupyterLab version, which sometimes introduces breakages that have nothing to do with their extension’s actual code.
Users still occasionally run into installation issues that trace back to the incomplete migration from “source” extensions to prebuilt ones.

The need to separate the build system was identified back in jupyterlab#13456, and initial work began during GSoC 2024. With the support of the Jupyter Foundation’s first community-funded proposal, we’ve now brought that work to a stable release.

What `jupyter-builder` does

jupyter-builder extracts all the Node.js-based build tooling out of JupyterLab into a dedicated package. You install it on its own, and it builds your extension, no full JupyterLab installation required.

It ships in two parts:

jupyter-builder (PyPI) — the Python package that provides the jupyter-builder CLI.
@jupyter/builder (npm) — the underlying JavaScript package containing the build scripts. The Python CLI invokes build-labextension.js from this package, which then runs the rspack compiler with all the configuration needed to produce a JupyterLab extension.

Instead of jupyter labextension build ., you now run:

jupyter-builder build .

Build compatibility without JupyterLab installed

One interesting problem we had to solve: if JupyterLab isn’t installed, how does the builder verify that an extension is compatible with a given JupyterLab version?

The answer is @jupyterlab/core-meta, a small npm package that publishes JupyterLab’s core metadata on its own. @jupyter/builder declares a dependency on a specific @jupyterlab/core-meta version, so by default your extension is checked for compatibility against whatever JupyterLab version that pin corresponds to. In general, the latest @jupyter/builder will track the latest JupyterLab.

If you want to build against a different JupyterLab version, pass --core-version:

jupyter-builder build . --core-version 4.4.x

We’ll download that version’s metadata from @jupyterlab/core-meta on npm and check compatibility against it.

Migrating an existing extension

If you’re starting a new extension with the extension template, you’ll get all of this set up automatically. For existing extensions, there are two changes to make.

1. Update the Python build dependencies

In your pyproject.toml, swap jupyterlab for jupyter-builder:

# Before
requires = ["hatchling>=1.5.0", "jupyterlab>=4.0.0,<5", "hatch-nodejs-version>=0.3.2"]

# After
requires = ["hatchling>=1.5.0", "jupyter-builder>=1.0.0", "hatch-nodejs-version>=0.3.2"]

Then update the scripts section of your package.json to use the new CLI:

"build:labextension": "jupyter-builder build .",
"build:labextension:dev": "jupyter-builder build --development True .",
"watch:labextension": "jupyter-builder watch ."

Your build no longer pulls in all of JupyterLab.

2. Update the npm builder dependency

Replace @jupyterlab/builder with @jupyter/builder in your package.json:

"@jupyter/builder": "^1.0.0"

jupyter-builder is backwards-compatible with @jupyterlab/builder, so things will keep working if you don’t migrate immediately. That said, we strongly recommend switching: @jupyterlab/builder is no longer being actively developed, and all new work is happening in @jupyter/builder.

Note that as part of this transition JupyterLab has also moved from Webpack to Rspack. Most extensions won’t need any changes, but if yours uses a custom webpackConfig see the Rspack migration notes.

What’s next

This release is the first stable foundation. We’re continuing to:

Migrate more packages across the Jupyter organization to use jupyter-builder.
Make the builder more configurable, so it can eventually be used for projects beyond JupyterLab.

If you maintain an extension, please try the migration and let us know how it goes. Feedback from real extensions is the best way to make sure the migration path stays smooth.

Acknowledgements

This work was funded under the first round of Jupyter Community Funded Proposals. We want to thank the Jupyter Foundation and everyone involved in setting up this funding mechanism.

A huge thank you to Nicholas Bollweg for many thoughtful discussions on the design and packaging of jupyter-builder, and to Jeremy Tuloup for helping us resolve issues and for guiding the adoption of jupyter-builder in Jupyter Notebook.

This package was initially created during GSoC 2024 by Ronan Coutinho, mentored by Frédéric Collonval. Their work laid the foundation that made this release possible.

About the developers

Darshan Paudyal is an intern at OpenTeams and a member of the Jupyter Frontend Council. Darshan led the work to bring jupyter-builder to a stable release, completing the separation from JupyterLab core and shepherding the package through to its first published version.

Michał Krassowski is a Senior Software Engineer at OpenTeams. Mike provided guidance and technical direction throughout the development of jupyter-builder, helping shape its architecture and roadmap.

Useful links

📦 PyPI: jupyter-builder
📦 npm: @jupyter/builder
💻 Source: github.com/jupyterlab/jupyter-builder
📖 Migration guide: jupyter-builder migration section
💬 Issues & feedback: GitHub issues

Catching Jupyter-specific bugs before CI does: announcing jupyter eslint plugin

2026-06-11T15:13:00+00:00

We’re excited to announce the release of the first version of the Jupyter ESLint plugin @jupyter/eslint-plugin, now available on npm. It’s a custom ESLint plugin designed specifically for the official Jupyter frontends (JupyterLab, Notebook, JupyterLite) and TypeScript extensions built around them.

Motivation

If you’ve ever written a JupyterLab extension, you’ve probably hit something like this:

You wire up a new plugin, push a PR, walk away to make coffee, and 30 minutes later CI fails on a test you didn’t expect to be related. You scroll through logs, eventually trace it back, and realize the problem was a single misaligned argument in your activate function. TypeScript was happy. The editor showed no red squiggles. Nothing in your local toolchain said a word.

And the slow CI feedback loop is only half the story. Some of these mistakes don’t fail CI at all, a hardcoded English label, an enum in a settings schema, a malformed token id. They pass tests, ship to users, and only surface at runtime. They’re the kind of bugs you hear about from users months later, if at all.

JupyterLab, Jupyter Notebook, and the wider extension ecosystem follow a lot of project-specific patterns around plugins, commands, tokens, settings schemas, translations, and visual tests. These patterns aren’t enforced by TypeScript, because they live one level above the type system. They’re contracts about how the framework expects code to be written, not about whether the code type-checks.

A few examples of what generic linters and TypeScript can’t catch:

A JupyterFrontEndPlugin that requires [TokenA, TokenB] but whose activate function takes those arguments in the wrong order. Both are tokens, both type-check but the plugin fails at activation.
A command added with commands.addCommand(...) whose label is a hardcoded English string. The extension ships, gets translated by the community, and that one button silently stays in English.

These are real, recurring issues. They cost contributor time, they frustrate first-time contributors, and they pile onto reviewer load. They’re exactly the kind of knowledge that lives in the heads of long-time maintainers and exactly the kind of knowledge that a linter is great at encoding. So we built one.

What v1 catches

The plugin currently ships eight rules, grouped by what they protect:

Plugin structure

plugin-activation-args — Keeps activate function arguments aligned with requires and optional tokens.
plugin-description — Requires a non-empty description on every JupyterFrontEndPlugin.
token-format — Enforces the <package>:<TokenSymbol> convention for new Token(...) ids.

Commands and settings

command-described-by — Requires a describedBy schema on commands that accept args.
no-schema-enum — Disallows enum in settings JSON schemas in favor of translatable oneOf with const and title.

Internationalization

no-untranslated-string — Flags hardcoded user-facing strings in command labels, dialogs, accessibility attributes, JSX, and more.
no-translation-concatenation — Forbids dynamic concatenation inside trans.__() calls that translation extractors can’t pick up.

Testing

require-soft-assertions-before-snapshots — Requires expect.soft(...) for all but the last snapshot in a Playwright test, so a single failure doesn’t block the rest from updating.

Each rule has incorrect/correct examples, options, and rationale in the rules reference.

Getting started in 60 seconds

Install the plugin:

npm install --save-dev @jupyter/eslint-plugin

Add it to your ESLint fconfig and turn on the recommended ruleset:

javascript

import jupyterPlugin from '@jupyter/eslint-plugin';

export default [
  {
    plugins: {
      jupyter: jupyterPlugin
    }
  },
  jupyterPlugin.configs.recommended
];

That’s it. Run jlpm eslint and you’ll start seeing Jupyter-specific issues alongside your existing lint output. If you’re still on legacy .eslintrc configs, there’s a recommended-legacy config too. However, we strongly recommend upgrading to ESLint v9 and using the new flat config format.

Full setup details, including type-aware configuration for plugin-activation-args and the JSON parser setup for no-schema-enum, are in the user guide.

If you maintain an extension, the most useful thing you can do today is install it and run it once on your codebase. Even if you don’t adopt it permanently, the first run is often informative most extensions surface a handful of issues they didn’t know they had.

Help us encode more knowledge

Eight rules is a starting point. The plugin is most valuable when it captures the recurring mistakes that maintainers across the ecosystem keep running into and a lot of that knowledge isn’t written down anywhere.

If you’ve ever been bitten by a Jupyter-specific issue that could have been a lint rule, something where you found yourself thinking “I wish my editor had warned me about this” please open an issue on the repository. Even a short description of the bug and a minimal example helps. We’d much rather encode that knowledge into an automated check once than have every new contributor learn it the hard way.

Acknowledgement

This work was funded under the first round of Jupyter Community Funded Proposals. We want to thank the Jupyter Foundation and everyone involved in setting up this funding mechanism.

We’re also grateful to Jeremy Tuloup and Nicolas Brichet for their help in adopting the plugin.

About the developers

Darshan Paudyal is an intern at OpenTeams and a member of the Jupyter Frontend Council. Darshan led the development of v1 of @jupyter/eslint-plugin, designing and implementing the rule set, the documentation, and the release.

Michał Krassowski is a Senior Software Engineer at OpenTeams. Mike provided guidance and direction for the development of the plugin.

Jupyter Blog - Darshan Kr. Paudyal

Announcing jupyter-builder: A Standalone Build System for JupyterLab Extensions

Motivation

What jupyter-builder does

Build compatibility without JupyterLab installed

Migrating an existing extension

1. Update the Python build dependencies

2. Update the npm builder dependency

What’s next

Acknowledgements

About the developers

Useful links

Catching Jupyter-specific bugs before CI does: announcing jupyter eslint plugin

Motivation

What v1 catches

Getting started in 60 seconds

Help us encode more knowledge

Acknowledgement

About the developers

Useful links

What `jupyter-builder` does