cheat sheet
pygmentize
Highlight source code from the command line — many lexers, many output formats.
pygmentize
What it is
pygmentize is the command-line interface shipped with the Pygments library. It takes source code on stdin or as a file argument and emits highlighted output in any of Pygments' formatter targets — HTML for docs, ANSI for terminals, LaTeX for typesetting, RTF for word processors, plus a few rarer formats. It's the tool behind countless documentation pipelines, plus a working cat-replacement for terminal viewing of source.
The package itself (pygments) is covered in depth in the packages reference. This page is the CLI cheat sheet — what pygmentize does, the flags worth memorising, and the four or five recipes that come up over and over.
Install
pygmentize is the entry-point script of the Pygments distribution. Install Pygments and you get the CLI.
pip install pygments
Output: (none — installs the library and the pygmentize command together)
pipx install pygments # isolated, CLI on $PATH globally
Output: pygmentize available on $PATH with no shared venv.
pygmentize -V
Output: Pygments version 2.19.x, (c) 2006-2026 by Georg Brandl and Pygments contributors.
Day-to-day commands
pygmentize hello.py
Output: the file printed with terminal-ANSI colors using the default style. The lexer is auto-detected from the .py extension.
pygmentize -L
Output: lists every available lexer, formatter, style, and filter. Long — pipe to less.
pygmentize -L lexer
pygmentize -L formatter
pygmentize -L style
Output: narrower listings — just lexers, just formatters, just styles. Use these to confirm a name before passing it to -l/-f/-O style=....
pygmentize -f html -o page.html hello.py
Output: writes page.html — a <div class="highlight"><pre>...</pre></div> block with token-class spans.
pygmentize -O style=monokai -f html -o page.html hello.py
Output: same HTML wrapper, but the inline style attributes (or referenced CSS classes) match Monokai. Combine with -O full=True to embed a full HTML document including <style>.
pygmentize -S monokai -f html > pygments.css
Output: writes the CSS file matching the Monokai style to standard output. Pair with the HTML output above.
pygmentize -f terminal256 -O style=dracula hello.py
Output: 256-color ANSI to stdout — far prettier than the default 16-color terminal formatter. Pipe through less -R to keep colors.
Common scenarios
The CLI is small enough that most use boils down to these five patterns.
Recipe 1 — Highlight a code file to a standalone HTML page
pygmentize -f html -O full=True,style=monokai -o page.html src/app.py
Output: page.html — a complete document with <!doctype html>, <style> block, and the highlighted source. Useful for one-off shares; not what you'd use for a documentation pipeline.
Recipe 2 — Pretty cat in the terminal (a bat substitute)
pygmentize -f terminal256 -O style=monokai script.sh | less -R
Output: ANSI-colorized source piped to a pager. -R makes less honor the escape sequences. For a more permanent fix, alias:
alias pcat='pygmentize -f terminal256 -O style=monokai'
pcat src/main.rs
Output: src/main.rs printed in ANSI colors using Monokai. The real bat CLI (Rust) is faster and supports line numbers and git diffs, but pygmentize is one pip install away.
Recipe 3 — Generate the matching CSS once, reuse forever
pygmentize -S default -f html -a .codehilite > pygments.css
Output: CSS with every rule scoped under .codehilite. Include it once in your site's <head>. Now every <div class="codehilite"> Pygments emits matches.
Recipe 4 — LaTeX output for typeset PDFs
pygmentize -f latex -O full=True,style=tango -o code.tex hello.py
pdflatex code.tex
Output: code.tex (a complete LaTeX file) and code.pdf (after pdflatex). For partial LaTeX (snippets you embed in another doc), drop full=True and use just the \PY{...} colorized lines plus the style preamble.
Recipe 5 — Detect the lexer when extension is missing or wrong
cat unknown.txt | pygmentize -g
Output: Pygments runs every lexer's analyse_text heuristic and highlights with the winner. -g is slow on large inputs — for repeated use, hard-code with -l <name>.
Recipe 6 — Highlight stdin to ANSI, by language hint
echo 'for i in 0..3 { println!("{i}") }' | pygmentize -l rust -f terminal256
Output: the Rust line, colored. -l rust skips auto-detection. Find names with pygmentize -L lexer | grep -i rust.
Recipe 7 — Add line numbers to HTML output
pygmentize -f html -O linenos=table -o page.html src/app.py
Output: HTML with a side column of line numbers. linenos=inline for inline numbering; linenos=table produces a two-column <table> with the numbers selectable separately from the code.
Useful flags
| Flag | Meaning |
|---|---|
-l <lexer> | Force a lexer (-l python, -l rust, -l bash). |
-g | Guess lexer from content (slow). |
-f <formatter> | Output format (html, terminal, terminal256, latex, rtf, bbcode, img, …). |
-O <opts> | Comma-separated formatter options (style=monokai,linenos=table,full=True). |
-S <style> | Print the CSS/style sheet for a style (paired with -f html or -f latex). |
-a <selector> | CSS selector to scope -S output (-a .codehilite). |
-o <path> | Write to file rather than stdout. |
-L [type] | List installed lexers / formatters / styles / filters. |
-H <type> <name> | Print help for a specific lexer/formatter/etc. (-H formatter html). |
-F <filter> | Apply a Pygments filter (e.g. -F highlight:names=foo,bar). |
-N <filename> | Detect lexer from filename without highlighting (returns the lexer name). |
-V | Print version. |
-h | Help summary. |
Configuration — styles, line numbers, anchors
Pygments has no separate config file — everything goes through -O <opts>. The options worth knowing:
-O option | Effect |
|---|---|
style=monokai | Pick a built-in style. List with pygmentize -L style. |
full=True | Emit a complete document (HTML or LaTeX) including the style preamble. |
linenos=table | Two-column line numbers (HTML). |
linenos=inline | Inline line numbers (HTML). |
lineanchors=line | Wrap each line in <a name="line-N">. Generates clickable line URLs. |
anchorlinenos=True | Make the line numbers themselves clickable links. |
cssclass=highlight | CSS class wrapping the <div> and <pre>. Must match the -a flag used to generate the matching CSS. |
bg=light | Background hint (some terminal formatters use this). |
wrapcode=True | Wrap output in <code>. Default is bare <pre> only. |
nobackground=True | Strip background color from terminal/HTML output. |
encoding=utf-8 | Output encoding. Default detection works for most cases. |
escapeinside=\\(\\) | Use LaTeX escape sequences (LaTeX formatter). |
pygmentize -f html -O style=monokai,linenos=table,lineanchors=line,anchorlinenos=True -o page.html src/app.py
Output: HTML with Monokai colors, table-style line numbers, and a clickable anchor on each line — a documentation-site-quality block in one command.
Common pitfalls
Lexer ambiguity for .txt, .in, generic files
Files without a recognised extension fall back to TextLexer, which highlights nothing. Use -l <name> to force or -g to guess. For build scripts named Dockerfile (no extension), pygmentize -l docker is the only reliable option.
Style names change across versions
monokai, dracula, friendly, solarized-light, solarized-dark are stable. Some niche styles have been renamed across 2.x minor versions — pin the Pygments version in your docs pipeline if your CSS depends on specific class names.
-a selector must match cssclass option
If you generate the CSS with pygmentize -S monokai -f html -a .codehilite > pygments.css but emit HTML with -O cssclass=highlight, the rules won't apply. Either align the names or use the default .highlight everywhere.
terminal (16-color) is washed out
The default ANSI formatter uses 16 colors, which most styles look bad in. Use -f terminal256 for 256-color or -f terminal16m for true-color terminals. Modern macOS/Linux terminals and Windows Terminal all support truecolor.
-g is slow
Each lexer's analyse_text runs on every guess. On a 1 MB input or in a loop over thousands of files, -g becomes the bottleneck. Always pass -l if you can.
pygmentize doesn't read syntax from a shebang automatically
pygmentize script (no extension, no -l) doesn't peek at #!/usr/bin/env python3 and pick python. Pass -l python or use -g.
Combining options with commas, not spaces
-O style=monokai,linenos=table — comma-separated, no spaces around ,. -O style=monokai linenos=table would interpret linenos=table as a positional argument and fail.
HTML output's class names
By default, pygmentize -f html emits <span class="k"> (Keyword), <span class="s"> (String), etc. These are short and pleasant to read but collide easily with site CSS that uses single-letter classes. Use -O classprefix=pyg- to namespace them.
See also
- Packages: pip-pygments — the Pygments library, lexer/formatter API