Styles

Pygments comes with some builtin styles that work for both the HTML and LaTeX formatter.

The builtin styles can be looked up with the get_style_by_name function:

>>> from pygments.styles import get_style_by_name
>>> get_style_by_name('colorful')
<class 'pygments.styles.colorful.ColorfulStyle'>

You can pass a instance of a Style class to a formatter as the style option in form of a string:

>>> from pygments.styles import get_style_by_name
>>> from pygments.formatters import HtmlFormatter
>>> HtmlFormatter(style='colorful').style
<class 'pygments.styles.colorful.ColorfulStyle'>

Or you can also import your own style (which must be a subclass of pygments.style.Style) and pass it to the formatter:

>>> from yourapp.yourmodule import YourStyle
>>> from pygments.formatters import HtmlFormatter
>>> HtmlFormatter(style=YourStyle).style
<class 'yourapp.yourmodule.YourStyle'>

Creating Own Styles

So, how to create a style? All you have to do is to subclass Style and define some styles:

from pygments.style import Style
from pygments.token import Keyword, Name, Comment, String, Error, \
     Number, Operator, Generic

class YourStyle(Style):
    default_style = ""
    styles = {
        Comment:                'italic #888',
        Keyword:                'bold #005',
        Name:                   '#f00',
        Name.Function:          '#0f0',
        Name.Class:             'bold #0f0',
        String:                 'bg:#eee #111'
    }

That’s it. There are just a few rules. When you define a style for Name the style automatically also affects Name.Function and so on. If you defined 'bold' and you don’t want boldface for a subtoken use 'nobold'.

(Philosophy: the styles aren’t written in CSS syntax since this way they can be used for a variety of formatters.)

default_style is the style inherited by all token types.

To make the style usable for Pygments, you must

  • either register it as a plugin (see the plugin docs)

  • or drop it into the styles subpackage of your Pygments distribution one style class per style, where the file name is the style name and the class name is StylenameClass. For example, if your style should be called "mondrian", name the class MondrianStyle, put it into the file mondrian.py and this file into the pygments.styles subpackage directory.

Style Rules

Here a small overview of all allowed styles:

bold

render text as bold

nobold

don’t render text as bold (to prevent subtokens being highlighted bold)

italic

render text italic

noitalic

don’t render text as italic

underline

render text underlined

nounderline

don’t render text underlined

bg:

transparent background

bg:#000000

background color (black)

border:

no border

border:#ffffff

border color (white)

#ff0000

text color (red)

noinherit

don’t inherit styles from supertoken

Note that there may not be a space between bg: and the color value since the style definition string is split at whitespace. Also, using named colors is not allowed since the supported color names vary for different formatters.

Furthermore, not all lexers might support every style.

Builtin Styles

Pygments ships some builtin styles which are maintained by the Pygments team.

To get a list of known styles you can use this snippet:

>>> from pygments.styles import STYLE_MAP
>>> STYLE_MAP.keys()
['default', 'emacs', 'friendly', 'colorful']

Getting a list of available styles

New in version 0.6.

Because it could be that a plugin registered a style, there is a way to iterate over all styles:

>>> from pygments.styles import get_all_styles
>>> styles = list(get_all_styles())

Terminal Styles

New in version 2.2.

Custom styles used with the 256-color terminal formatter can also map colors to use the 8 default ANSI colors. To do so, use ansigreen, ansibrightred or any other colors defined in pygments.style.ansicolors. Foreground ANSI colors will be mapped to the corresponding escape codes 30 to 37 thus respecting any custom color mapping and themes provided by many terminal emulators. Light variants are treated as foreground color with and an added bold flag. bg:ansi<color> will also be respected, except the light variant will be the same shade as their dark variant.

See the following example where the color of the string "hello world" is governed by the escape sequence \x1b[34;01m (Ansi bright blue, Bold, 41 being red background) instead of an extended foreground & background color.

>>> from pygments import highlight
>>> from pygments.style import Style
>>> from pygments.token import Token
>>> from pygments.lexers import Python3Lexer
>>> from pygments.formatters import Terminal256Formatter

>>> class MyStyle(Style):
        styles = {
            Token.String:     'ansibrightblue bg:ansibrightred',
        }

>>> code = 'print("Hello World")'
>>> result = highlight(code, Python3Lexer(), Terminal256Formatter(style=MyStyle))
>>> print(result.encode())
b'\x1b[34;41;01m"\x1b[39;49;00m\x1b[34;41;01mHello World\x1b[39;49;00m\x1b[34;41;01m"\x1b[39;49;00m'

Colors specified using ansi* are converted to a default set of RGB colors when used with formatters other than the terminal-256 formatter.

By definition of ANSI, the following colors are considered “light” colors, and will be rendered by most terminals as bold:

  • “brightblack” (darkgrey), “brightred”, “brightgreen”, “brightyellow”, “brightblue”, “brightmagenta”, “brightcyan”, “white”

The following are considered “dark” colors and will be rendered as non-bold:

  • “black”, “red”, “green”, “yellow”, “blue”, “magenta”, “cyan”, “gray”

Exact behavior might depends on the terminal emulator you are using, and its settings.

Changed in version 2.4.

The definition of the ANSI color names has changed. New names are easier to understand and align to the colors used in other projects.

New names

Pygments up to 2.3

ansiblack

#ansiblack

ansired

#ansidarkred

ansigreen

#ansidarkgreen

ansiyellow

#ansibrown

ansiblue

#ansidarkblue

ansimagenta

#ansipurple

ansicyan

#ansiteal

ansigray

#ansilightgray

ansibrightblack

#ansidarkgray

ansibrightred

#ansired

ansibrightgreen

#ansigreen

ansibrightyellow

#ansiyellow

ansibrightblue

#ansiblue

ansibrightmagenta

#ansifuchsia

ansibrightcyan

#ansiturquoise

ansiwhite

#ansiwhite

Old ANSI color names are deprecated but will still work.