Documentation
Command Line Interface
back to documentation indexTable of contents
You can use Pygments from the shell, provided you installed the pygmentize script:
$ pygmentize test.py print "Hello World"
will print the file test.py to standard output, using the Python lexer (inferred from the file name extension) and the terminal formatter (because you didn't give an explicit formatter name).
If you want HTML output:
$ pygmentize -f html -l python -o test.html test.py
As you can see, the -l option explicitly selects a lexer. As seen above, if you give an input file name and it has an extension that Pygments recognizes, you can omit this option.
The -o option gives an output file name. If it is not given, output is written to stdout.
The -f option selects a formatter (as with -l, it can also be omitted if an output file name is given and has a supported extension). If no output file name is given and -f is omitted, the TerminalFormatter is used.
The above command could therefore also be given as:
$ pygmentize -o test.html test.py
To create a full HTML document, including line numbers and stylesheet (using the "emacs" style), highlighting the Python file test.py to test.html:
$ pygmentize -O full,style=emacs -o test.html test.py
Options and filters
Lexer and formatter options can be given using the -O option:
$ pygmentize -f html -O style=colorful,linenos=1 -l python test.py
Be sure to enclose the option string in quotes if it contains any special shell characters, such as spaces or expansion wildcards like *. If an option expects a list value, separate the list entries with spaces (you'll have to quote the option value in this case too, so that the shell doesn't split it).
Since the -O option argument is split at commas and expects the split values to be of the form name=value, you can't give an option value that contains commas or equals signs. Therefore, an option -P is provided (as of Pygments 0.9) that works like -O but can only pass one option per -P. Its value can then contain all characters:
$ pygmentize -P "heading=Pygments, the Python highlighter" ...
Filters are added to the token stream using the -F option:
$ pygmentize -f html -l pascal -F keywordcase:case=upper main.pas
As you see, options for the filter are given after a colon. As for -O, the filter name and options must be one shell word, so there may not be any spaces around the colon.
Generating styles
Formatters normally don't output full style information. For example, the HTML formatter by default only outputs <span> tags with class attributes. Therefore, there's a special -S option for generating style definitions. Usage is as follows:
$ pygmentize -f html -S colorful -a .syntax
generates a CSS style sheet (because you selected the HTML formatter) for the "colorful" style prepending a ".syntax" selector to all style rules.
For an explanation what -a means for a particular formatter, look for the arg argument for the formatter's get_style_defs() method.
Getting lexer names
New in Pygments 1.0.
The -N option guesses a lexer name for a given filename, so that
$ pygmentize -N setup.py
will print out python. It won't highlight anything yet. If no specific lexer is known for that filename, text is printed.
Getting help
The -L option lists lexers, formatters, along with their short names and supported file name extensions, styles and filters. If you want to see only one category, give it as an argument:
$ pygmentize -L filters
will list only all installed filters.
The -H option will give you detailed information (the same that can be found in this documentation) about a lexer, formatter or filter. Usage is as follows:
$ pygmentize -H formatter html
will print the help for the HTML formatter, while
$ pygmentize -H lexer python
will print the help for the Python lexer, etc.
A note on encodings
New in Pygments 0.9.
Pygments tries to be smart regarding encodings in the formatting process:
- If you give an encoding option, it will be used as the input and output encoding.
- If you give an outencoding option, it will override encoding as the output encoding.
- If you don't give an encoding and have given an output file, the default encoding for lexer and formatter is latin1 (which will pass through all non-ASCII characters).
- If you don't give an encoding and haven't given an output file (that means output is written to the console), the default encoding for lexer and formatter is the terminal encoding (sys.stdout.encoding).
Did you like the documentation? Do you have suggestions? Leave your comment here!
briannabirman@gmail.com wrote on Sept. 29, 2011:
I'm developing a lexer for an unsupported language and want to be able to test it as I go. Is there
a command similar to the one below that allows you to specify a specific file to use as the lexer rather than just the language name?
$ pygmentize -f html -l python -o test.html test.py
matandked@gmail.com wrote on Sept. 1, 2011:
Hello, is there any possibility to set code page for pygmentize? When I prepare files, polish special characters has been substituted by strange symbols.
ajuanpi wrote on Sept. 30, 2010:
Ok, ok,
My fault. Help was a little hard to find, but is there. Thanks guys. The solution
$ pygmentize -f latex -O full -l c code.c > code.tex
Any suggestions for nice styles? This one makes lines too large, specially comments.
ajuanpi@gmail.com wrote on Sept. 30, 2010:
Hi,
I think this tool is really nice....
I tried
pygmentize -f tex -l c code.c
and I get a unusable latex code. The issues start with \section{Verbatim} with caps, when latex only accepts \section{verbatim}...
afterwards I get all this \PY{} commands that I cannot understand.
Is the latex functionality working?
Thanks
paul@cravenfamily.com wrote on Jan. 20, 2010:
The heading option doesn't do anything for me. I'd like to see a full listing of all options somewhere.
mike wrote on Nov. 21, 2009:
Same here, please move the html example to the top! ;)
looseBrie wrote on Nov. 4, 2009:
It'd be great to see an example here that demonstrated LaTeX output, since it's my favourite feature.
mds wrote on Nov. 2, 2009:
@arw1961
$ pygmentize -O full,style=emacs -o setup.html setup.py
Yeah, I was looking for that as well- deserves a more prominent spot on the side.
Besides that: Thanks for the great work- it does exactly what I need!
antisym wrote on Oct. 15, 2009:
Wrote this batch file for Windows to view a subversion diff in Chrome using the TRAC style:
@ECHO OFF
svn diff %1 > crnt.diff
python pygmentize -f html -O style=trac -O full -o crnt.html crnt.diff && chrome.exe --app=file://%CD%/crnt.html && del crnt.diff
ian Dees wrote on May 21, 2009:
I'd love to see the ability to specify a custom formatter on the command line; maybe the -f flag could take either an existing formatter name (e.g., html) or a Python filename (e.g., my_custom_formatter.py).
chillu wrote on March 31, 2009:
@arw1961
$ pygmentize -O full,style=emacs -o setup.html setup.py
* I too was looking for a quick way to do that in the documentation.
Somewhat frustratingly its at the very end.
Georg wrote on March 5, 2008:
Good idea! I've added an examples section now.
arw1961@yahoo.com wrote on March 4, 2008:
It would be great if you could show a simple sequence that constructs a complete HTML document. I'm sure I can figure it out, but I'd rather be spoon fed :). Also readers with less background may not be able to figure it out and just throw up their hands. My initial test didn't look like much in the browser -- but when I view source I see that the styles are all there... I just need to add a stylesheet... After I find one...