Pygments

2.19.2 verified Tue May 12 auth: no python install: verified quickstart: verified

Pygments is a generic syntax highlighting library written in Python, supporting over 500 languages and text formats with output in HTML, LaTeX, RTF, SVG, image formats, and ANSI terminal sequences. It can be used both as a library and as the `pygmentize` CLI tool. Current version is 2.19.2. Releases are made periodically with new lexers added each minor version; patch releases fix regressions quickly (2.19.1 and 2.19.2 followed 2.19.0 within weeks).

pip install Pygments

Common errors

error ModuleNotFoundError: No module named 'pygments' ↓

cause The Pygments library is not installed in the current Python environment.

fix

Install Pygments using pip: pip install pygments.

error ImportError: No module named pygments.styles ↓

cause The Pygments library is not installed or not accessible in the current Python environment.

fix

Ensure Pygments is installed: pip install pygments.

error ImportError: No module named 'pygments.lexer' ↓

cause The Pygments library is not installed or not accessible in the current Python environment.

fix

Ensure Pygments is installed: pip install pygments.

error ImportError: No module named 'pygments.lexers._asy_builtins' ↓

cause The Pygments library is not installed or not accessible in the current Python environment.

fix

Ensure Pygments is installed: pip install pygments.

error ImportError: No module named 'pygments' ↓

cause The Pygments library is not installed or not accessible in the current Python environment.

fix

Ensure Pygments is installed: pip install pygments.

Warnings

gotcha HtmlFormatter output does NOT include CSS by default. The generated HTML uses CSS classes but the stylesheet must be obtained separately via `formatter.get_style_defs('.highlight')` and injected into the page. Without it the output appears unstyled. ↓

fix Call `HtmlFormatter().get_style_defs('.highlight')` and embed or link the result. Use `HtmlFormatter(full=True)` to get a self-contained HTML document, or `noclasses=True` for inline styles (not recommended for large code blocks).

breaking Python 3.7 and below are no longer supported as of Pygments 2.18.0. The `importlib-metadata` backport is no longer required or used. The `pip install Pygments[plugins]` extra is a no-op. ↓

fix Upgrade to Python >=3.8. Remove any explicit `importlib-metadata` dependency added for Pygments plugin discovery.

gotcha All lexer/formatter/style lookup functions (`get_lexer_by_name`, `get_lexer_for_filename`, `get_formatter_by_name`, etc.) raise `pygments.util.ClassNotFound` — not a built-in like `KeyError` or `ValueError` — when no match is found. Uncaught, this crashes silently in many frameworks. ↓

fix Always wrap lookup calls in `try/except pygments.util.ClassNotFound`. Fall back to `get_lexer_by_name('text')` (the plain-text lexer) for safe passthrough.

gotcha Pygments provides no execution-time guarantees. Certain inputs (especially adversarial or malformed code) can trigger catastrophic backtracking in lexer regexes, causing the process to hang or consume excessive memory. This is a known DoS vector for web services. ↓

fix Always enforce a timeout when calling Pygments on untrusted user input (e.g. run in a subprocess with `subprocess.run(..., timeout=5)`). Limit concurrent Pygments processes to avoid resource exhaustion.

gotcha `get_lexer_for_filename()` only checks the primary (unique) filename list and can raise `ClassNotFound` for ambiguous extensions like `.html`. `guess_lexer_for_filename()` also checks secondary patterns and runs content analysis, but is slower. ↓

fix For ambiguous extensions use `guess_lexer_for_filename(filename, content)`. Always catch `ClassNotFound` from both functions.

gotcha The `cssclass` option on `HtmlFormatter` must match the selector prefix passed to `get_style_defs()`. If you set `cssclass='source'` but call `get_style_defs('.highlight')`, the CSS will not apply to the generated markup. ↓

fix Keep them in sync: `fmt = HtmlFormatter(cssclass='source')` then `fmt.get_style_defs('.source')`. Or rely on the default cssclass `'highlight'` and pass `'.highlight'` to `get_style_defs()`.

deprecated `STYLE_MAP` in `pygments.styles` uses an older format and does not include plugin styles. It is kept for backwards compatibility but is incomplete. ↓

fix Use `from pygments.styles import get_all_styles; list(get_all_styles())` to enumerate all styles including those registered via plugins.

Install

pip install Pygments[windows-terminal]

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) Pygments - - 0.00s 26.3M

3.10 alpine (musl) windows-terminal - - 0.00s 26.5M

3.10 slim (glibc) Pygments - - 0.00s 27M

3.10 slim (glibc) windows-terminal - - 0.00s 27M

3.11 alpine (musl) Pygments - - 0.00s 29.0M

3.11 alpine (musl) windows-terminal - - 0.00s 29.2M

3.11 slim (glibc) Pygments - - 0.00s 29M

3.11 slim (glibc) windows-terminal - - 0.00s 30M

3.12 alpine (musl) Pygments - - 0.00s 20.8M

3.12 alpine (musl) windows-terminal - - 0.00s 21.0M

3.12 slim (glibc) Pygments - - 0.00s 21M

3.12 slim (glibc) windows-terminal - - 0.00s 21M

3.13 alpine (musl) Pygments - - 0.00s 20.4M

3.13 alpine (musl) windows-terminal - - 0.00s 20.7M

3.13 slim (glibc) Pygments - - 0.00s 21M

3.13 slim (glibc) windows-terminal - - 0.00s 21M

3.9 alpine (musl) Pygments - - 0.00s 25.7M

3.9 alpine (musl) windows-terminal - - 0.00s 26.0M

3.9 slim (glibc) Pygments - - 0.00s 26M

3.9 slim (glibc) windows-terminal - - 0.00s 26M

Imports

highlight
```
from pygments import highlight
```
Top-level entry point for all highlighting; always import from `pygments` directly.
PythonLexer (and other named lexers)
wrong
```
from pygments import PythonLexer
```
correct
```
from pygments.lexers import PythonLexer
```
All lexer classes live in `pygments.lexers`, not in the top-level `pygments` package.
get_lexer_by_name
```
from pygments.lexers import get_lexer_by_name
```
Dynamic lexer lookup by alias string, e.g. 'python'. Raises pygments.util.ClassNotFound on unknown alias.
get_lexer_for_filename
```
from pygments.lexers import get_lexer_for_filename
```
Selects lexer by filename pattern. Only uses the primary (unique) filename list; use guess_lexer_for_filename for ambiguous extensions.
guess_lexer
```
from pygments.lexers import guess_lexer
```
Analyses text content to pick a lexer. Raises ClassNotFound if no lexer scores above 0. May be slow on large inputs.
HtmlFormatter
wrong
```
from pygments import HtmlFormatter
```
correct
```
from pygments.formatters import HtmlFormatter
```
All formatter classes live in `pygments.formatters`, not the top-level package.
ClassNotFound
```
from pygments.util import ClassNotFound
```
Exception raised by all lexer/formatter/style lookup functions when no match is found. Must be caught explicitly.
get_all_styles
```
from pygments.styles import get_all_styles
```
Returns an iterator of all built-in and plugin style names. Use instead of STYLE_MAP for complete plugin-aware enumeration.
RegexLexer
```
from pygments.lexer import RegexLexer
```
Base class for custom lexer development. Note: singular `pygments.lexer`, not `pygments.lexers`.

Quickstart verified last tested: 2026-04-23

Highlight a Python snippet to HTML and print the required CSS alongside it.

from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import HtmlFormatter
from pygments.util import ClassNotFound

code = '''
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("World"))
'''

try:
    lexer = get_lexer_by_name('python', stripall=True)
except ClassNotFound as e:
    raise SystemExit(f"Lexer not found: {e}")

# cssclass must match the selector passed to get_style_defs
formatter = HtmlFormatter(linenos=True, cssclass='highlight', style='default')

# highlighted is an HTML snippet — NOT a full document
highlighted = highlight(code, lexer, formatter)

# get_style_defs() must be called to obtain the CSS; it is NOT embedded by default
css = formatter.get_style_defs('.highlight')

print(f'<style>\n{css}\n</style>')
print(highlighted)