jupyterlab_pygments

jupyterlab_pygments is a small, single-purpose Pygments style plugin maintained by the Jupyter organization. It defines a JupyterStyle class that maps Pygments token types (keywords, strings, comments, numbers, operators) onto the same CSS custom properties JupyterLab’s CodeMirror editor uses internally, so that syntax-highlighted code rendered through Pygments — in exported notebook HTML, documentation builds, or any tool that shells out to Pygments for highlighting — visually matches the colors a user sees live inside JupyterLab.

The package ships almost no runtime logic: a style.py module with the token-to-CSS-variable mapping and an __init__.py that registers the labextension path. Its only functional dependency is pygments itself. It is best known as a transitive dependency of nbconvert, which uses it by default when converting notebooks to HTML so that exported pages keep the JupyterLab look and feel rather than falling back to a generic Pygments theme.

What You Get

• JupyterStyle Pygments class - a ready-to-use Pygments style keyed to JupyterLab’s CodeMirror CSS variables for keywords, strings, comments, numbers, operators, and punctuation.
• Theme parity with the live editor - highlighted code in exported HTML or docs visually matches what a user sees inside the JupyterLab notebook editor, including light/dark theme switching since the coloring is CSS-variable driven, not baked-in.
• Zero-config nbconvert integration - installed automatically as a dependency of nbconvert, so most users get the matching theme without ever installing or configuring it directly.
• Minimal footprint - a single style module plus a JupyterLab labextension registration; no build step or runtime configuration required to use the Pygments style itself.
• Conda and PyPI distribution - installable via pip install jupyterlab_pygments or conda install -c conda-forge jupyterlab_pygments.

Common Use Cases

• Notebook-to-HTML export - nbconvert pulls in jupyterlab_pygments so jupyter nbconvert --to html output keeps JupyterLab-consistent code coloring rather than a mismatched default Pygments theme.
• Static documentation builds - Sphinx or MkDocs sites that embed notebook-derived code snippets get the same JupyterLab color palette as the authoring environment.
• Custom Pygments-based renderers - any tool that calls Pygments directly (e.g. pygments.highlight(code, PythonLexer(), HtmlFormatter(style='jupyterlab_pygments.JupyterStyle'))) can request the style by name for JupyterLab-matched output.
• Notebook preview services - internal tools or CI artifacts that render notebook cells as static HTML benefit from a theme that looks native to Jupyter rather than a generic code-highlighting look.

Under The Hood

Architecture The package has almost no architecture to speak of by design: a single jupyterlab_pygments/style.py module defines JupyterStyle(Style), a subclass of Pygments’ Style base class, mapping each Pygments token type (Comment, Keyword, String, Number, Operator, Punctuation, etc.) to a CSS variable string such as var(--jp-mirror-editor-comment-color). __init__.py re-exports JupyterStyle and implements _jupyter_labextension_paths() so JupyterLab’s extension loader can discover the accompanying (purely cosmetic, CSS-only) labextension bundle built from the src/ TypeScript stub. There is no request/response flow, no state, and no data layer — the entire runtime behavior is a static dict lookup Pygments performs when generating HTML class attributes and inline styles.

Tech Stack Pure Python at runtime (requires-python >= 3.8, no runtime dependencies declared in pyproject.toml beyond an implicit dependency on pygments). The build side uses hatchling with hatch-nodejs-version and hatch-jupyter-builder to derive the Python package version from package.json and to build a minimal JupyterLab labextension via jlpm/tsc and the @jupyterlab/builder toolchain — TypeScript, ESLint, Prettier, and Stylelint are present purely for that labextension packaging step, not for any application logic. CI (build.yml) validates the extension loads correctly via jupyter labextension list and python -m jupyterlab.browser_check, then builds and reinstalls the wheel in isolation to catch packaging regressions.

Code Quality There are no unit tests in the traditional sense — no tests/ directory or pytest suite. Verification is done at the CI/build level instead: the workflow installs the built wheel into a clean environment, asserts the labextension registers correctly, and runs JupyterLab’s own browser-based extension check. Given the package’s surface area (one style class, one static mapping), this build-and-load verification approach is proportionate; there is no business logic that would benefit from unit tests. Linting (ESLint/Prettier/Stylelint) applies only to the TypeScript/CSS labextension stub, and the Python side has no linter configured. Naming and structure are straightforward and consistent with the rest of the Jupyter ecosystem’s extension conventions.

API Design The public API is intentionally tiny: import JupyterStyle from jupyterlab_pygments, or reference the style by its Pygments entry-point name (jupyterlab_pygments.JupyterStyle / registered as jupyterlab_pygments with Pygments’ style registry). No configuration objects, no options, no boilerplate — this is the point of the package. Documentation is limited to the README’s installation instructions and a code comment in style.py listing the available CSS variables and known limitations (e.g. Pygments cannot distinguish object properties from bare names the way CodeMirror can), which is honest but sparse for anyone extending the style rather than just consuming it.