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 Standard install
• pip install Pygments[windows-terminal] Windows colored console output (Windows only)

Imports

• highlight

  from pygments import highlight

  Top-level entry point for all highlighting; always import from `pygments` directly.
• PythonLexer (and other named lexers)

  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

  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

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)