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.
Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Style
✓ from jupyterlab_pygments.style import Style
✗ from jupyterlab_pygments import Style
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))
Debug
Known issues
gotchaPygments-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.fixBe aware of these inherent limitations of Pygments styling when expecting an exact match to CodeMirror's rendering.
affects: All versions
gotchaWhen 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.fixEnsure 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.
affects: All versions
breakingThere 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.fixThis 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.
affects: All versions, particularly affecting package maintainers
deprecatedWhile `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.fixUpgrade 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.
affects: <4.0.0 (for host JupyterLab version)
breakingThe `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.fixEnsure `pygments` is installed in your Python environment using `pip install pygments` or by including it in your project's `requirements.txt`.
affects: All versions
breakingThe `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`.fixEnsure 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`).
affects: All versions (this is an environment setup issue, not specific to library versions)
Audit
Dependencies
pygmentsrequiredCore dependency for syntax highlighting; requires version >=2.4.1.