JupyterLab Pygments Theme

0.3.0 verified Tue May 12 auth: no python install: stale quickstart: stale

This package provides a syntax highlighting theme for Pygments, designed to leverage JupyterLab's CSS variables. It aims to integrate Pygments-generated HTML code blocks seamlessly with the visual styling of JupyterLab themes. The current version is 0.3.0, released on November 23, 2023, and it is actively maintained by the Jupyter Development Team.

pip install jupyterlab-pygments

Common errors

error jupyterlab-pygments theme not applying ↓

cause The JupyterLab Pygments theme might not be correctly activated or is being overridden by other JupyterLab theme settings.

fix

Ensure jupyterlab-pygments is installed, then navigate to JupyterLab's Settings -> Theme and select a JupyterLab theme that utilizes the Pygments CSS variables.

error LookupError: ... jupyterlab_pygments-0.2.2.tar.gz ... is already being built: jupyterlab-pygments ↓

cause This error typically occurs due to recursive or circular dependencies during `pip` installation, especially when attempting to build packages from source or in complex packaging environments.

fix

Install jupyterlab (which includes jupyterlab-pygments as a dependency) using pre-built wheels with pip install jupyterlab. If managing custom environments, ensure build-time dependencies are resolved without circular references.

error ModuleNotFoundError: No module named 'jupyterlab_pygments' ↓

cause The `jupyterlab-pygments` package is either not installed in the current Python environment or is not accessible in the Python path.

fix

Install the package using pip: pip install jupyterlab-pygments.

error Applying the Pygment's CSS to a notebook changes stuff outside pygments ↓

cause Pygments-generated HTML and CSS classes may not be sufficiently granular or prefixed, leading to styling conflicts where Pygments' styles unintentionally affect other elements in the JupyterLab notebook.

fix

When using HtmlFormatter from Pygments, provide a unique cssclass argument, which ensures the generated CSS is scoped and less likely to interfere with global JupyterLab styles. Alternatively, inject CSS with higher specificity to override unintended styling.

Warnings

gotcha Pygments-generated HTML and CSS classes from this theme are not as granular as JupyterLab's CodeMirror editor. This means some visual nuances, like differentiating properties from general names or how dots in `foo.bar` are styled, cannot be perfectly replicated. ↓

fix Be aware of these inherent limitations of Pygments styling when expecting an exact match to CodeMirror's rendering.

gotcha When directly embedding Pygments-generated HTML and CSS (especially with `HtmlFormatter`) into Jupyter Notebook/Lab cell outputs, the CSS can sometimes conflict with the global Jupyter theme, potentially affecting the readability of other output elements or applying unintended styles. ↓

fix Ensure that the generated HTML and CSS are properly scoped (e.g., by using a unique `cssclass` for the formatter and styling it appropriately) to minimize conflicts. Consider generating `full=True` output that includes the `<style>` tags for isolated styling.

breaking There have been reported issues with recursive build-time dependencies (e.g., `jupyterlab-pygments`, `jupyterlab`, `nbconvert`) leading to bootstrapping problems during packaging, especially when upgrading Python versions (e.g., 3.8 to 3.9). This can make it difficult for packagers to build and install these components. ↓

fix This is an ongoing issue being addressed by the JupyterLab team, with work moving towards a separate `jupyterlab-builder` package. Packagers should monitor the `jupyterlab/jupyterlab-builder` repository for updates and potential solutions.

deprecated While `jupyterlab-pygments` is a theme, its primary environment, JupyterLab 3, reached its end-of-maintenance on May 15, 2024, with critical fixes only until December 31, 2024. Users are strongly encouraged to upgrade to JupyterLab 4 for continued support and new features. ↓

fix Upgrade your JupyterLab installation to version 4.x or later. This theme should remain compatible across JupyterLab versions, but leveraging a current JupyterLab host is recommended.

breaking The `pygments` package is a core dependency for syntax highlighting and must be explicitly installed in the environment for scripts or applications that use it. A `ModuleNotFoundError` indicates that the package is missing. ↓

fix Ensure `pygments` is installed in your Python environment using `pip install pygments` or by including it in your project's `requirements.txt`.

breaking The `pygments` library, which is a fundamental dependency for `jupyterlab-pygments` and Pygments-related operations, is not found in the Python environment, leading to a `ModuleNotFoundError`. ↓

fix Ensure that the `pygments` package is installed in your Python environment. This can typically be resolved by running `pip install pygments` or by including it in your project's dependency management file (e.g., `requirements.txt`).

Install

conda install -c conda-forge jupyterlab_pygments

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

jupyterlab_pygments
```
import jupyterlab_pygments
```
While you can import the package, its primary function is to register a Pygments style named 'jupyterlab'. You typically use this style by name with Pygments' formatters, rather than directly importing symbols from the package itself for style application.
style='jupyterlab'
```
from pygments.formatters import HtmlFormatter
formatter = HtmlFormatter(style='jupyterlab')
```
The 'jupyterlab' style is automatically registered by Pygments when the package is installed. Access it by name when creating a Pygments formatter.

Quickstart stale last tested: 2026-04-23

This quickstart demonstrates how to use the `jupyterlab` Pygments style to highlight Python code and display it within a Jupyter environment. The `HtmlFormatter` is configured with `style='jupyterlab'` to apply the theme, and `full=True` to embed the necessary CSS.

from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter
from IPython.display import HTML, display

# Example Python code to highlight
code_to_highlight = """
def greet(name):
    print(f"Hello, {name}!")

greet("World")
"""

# Create an HTML formatter using the 'jupyterlab' style
# The style 'jupyterlab' is made available by the jupyterlab-pygments package
formatter = HtmlFormatter(style='jupyterlab', full=True, cssclass='highlight-jupyterlab')

# Generate the HTML output with highlighting
highlighted_html = highlight(code_to_highlight, PythonLexer(), formatter)

# To display in a Jupyter environment, use IPython.display
# For standalone use, you would typically write highlighted_html to a file.
# The 'full=True' option includes the <style> tags, making it self-contained.
display(HTML(highlighted_html))