coloredlogs: Colored terminal output for Python’s logging module

The coloredlogs package enables colored terminal output for Python’s logging module. The ColoredFormatter class inherits from logging.Formatter and uses ANSI escape sequences to render your logging messages in color. It uses only standard colors so it should work on any UNIX terminal. It’s currently tested on Python 2.6, 2.7, 3.4, 3.5, 3.6 and PyPy. On Windows coloredlogs automatically pulls in Colorama as a dependency and enables ANSI escape sequence translation using Colorama. Here is a screen shot of the demo that is printed when the command coloredlogs --demo is executed:

Note that the screenshot above includes custom logging levels defined by my verboselogs package: if you install both coloredlogs and verboselogs it will Just Work (verboselogs is of course not required to use coloredlogs).


The coloredlogs package is available on PyPI which means installation should be as simple as:

$ pip install coloredlogs

There’s actually a multitude of ways to install Python packages (e.g. the per user site-packages directory, virtual environments or just installing system wide) and I have no intention of getting into that discussion here, so if this intimidates you then read up on your options before returning to these instructions ;-).


Here’s an example of how easy it is to get started:

import coloredlogs, logging

# Create a logger object.
logger = logging.getLogger(__name__)

# By default the install() function installs a handler on the root logger,
# this means that log messages from your code and log messages from the
# libraries that you use will all show up on the terminal.

# If you don't want to see log messages from libraries, you can pass a
# specific logger object to the install() function. In this case only log
# messages originating from that logger will show up on the terminal.
coloredlogs.install(level='DEBUG', logger=logger)

# Some examples.
logger.debug("this is a debugging message")"this is an informational message")
logger.warning("this is a warning message")
logger.error("this is an error message")
logger.critical("this is a critical message")

Format of log messages

The ColoredFormatter class supports user defined log formats so you can use any log format you like. The default log format is as follows:

%(asctime)s %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s

This log format results in the following output:

2015-10-23 03:32:22 peter-macbook coloredlogs.demo[30462] DEBUG message with level 'debug'
2015-10-23 03:32:23 peter-macbook coloredlogs.demo[30462] VERBOSE message with level 'verbose'
2015-10-23 03:32:24 peter-macbook coloredlogs.demo[30462] INFO message with level 'info'

You can customize the log format and styling using environment variables as well as programmatically, please refer to the online documentation for details.

Enabling millisecond precision

If you’re switching from logging.basicConfig() to coloredlogs.install() you may notice that timestamps no longer include milliseconds. This is because coloredlogs doesn’t output milliseconds in timestamps unless you explicitly tell it to. There are two ways to do that:

  1. The easy way is to pass the milliseconds argument to coloredlogs.install():

  2. Alternatively you can change the log format to include ‘msecs’:

    %(asctime)s,%(msecs)03d %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s

    Here’s what the call to coloredlogs.install() would then look like:

    coloredlogs.install(fmt='%(asctime)s,%(msecs)03d %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s')

    Customizing the log format also enables you to change the delimiter that separates seconds from milliseconds (the comma above).

Colored output from cron

When coloredlogs is used in a cron job, the output that’s e-mailed to you by cron won’t contain any ANSI escape sequences because coloredlogs realizes that it’s not attached to an interactive terminal. If you’d like to have colors e-mailed to you by cron there are two ways to make it happen:

Modifying your crontab

Here’s an example of a minimal crontab:

* * * * * root coloredlogs --to-html your-command

The coloredlogs program is installed when you install the coloredlogs Python package. When you execute coloredlogs --to-html your-command it runs your-command under the external program script (you need to have this installed). This makes your-command think that it’s attached to an interactive terminal which means it will output ANSI escape sequences which will then be converted to HTML by the coloredlogs program. Yes, this is a bit convoluted, but it works great :-)

Modifying your Python code

The ColoredCronMailer class provides a context manager that automatically enables HTML output when the $CONTENT_TYPE variable has been correctly set in the crontab.

This requires my capturer package which you can install using pip install 'coloredlogs[cron]'. The [cron] extra will pull in capturer 2.4 or newer which is required to capture the output while silencing it - otherwise you’d get duplicate output in the emails sent by cron.

The context manager can also be used to retroactively silence output that has already been produced, this can be useful to avoid spammy cron jobs that have nothing useful to do but still email their output to the system administrator every few minutes :-).


The latest version of coloredlogs is available on PyPI and GitHub. The online documentation is available on Read The Docs. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at


This software is licensed under the MIT license.

© 2018 Peter Odding.

API documentation

The following documentation is based on the source code of version 9.0 of the coloredlogs package.

The most useful entry points into the documentation are install(), ColoredFormatter and enable_system_logging().

The coloredlogs module

Colored terminal output for Python’s logging module.

Getting started

The easiest way to get started is by importing coloredlogs and calling coloredlogs.install() (similar to logging.basicConfig()):

>>> import coloredlogs, logging
>>> coloredlogs.install(level='DEBUG')
>>> logger = logging.getLogger('')
>>>"this is an informational message")
2015-10-22 19:13:52 peter-macbook[28036] INFO this is an informational message

The install() function creates a ColoredFormatter that injects ANSI escape sequences into the log output.

Environment variables

The following environment variables can be used to configure the coloredlogs module without writing any code:

Environment variable Default value Type of value
$COLOREDLOGS_AUTO_INSTALL ‘false’ a boolean that controls whether auto_install() is called
$COLOREDLOGS_LOG_LEVEL ‘INFO’ a log level name

Examples of customization

Here we’ll take a look at some examples of how you can customize coloredlogs using environment variables.

About the defaults

Here’s a screen shot of the default configuration for easy comparison with the screen shots of the following customizations (this is the same screen shot that is shown in the introduction):

Screen shot of colored logging with defaults.

The screen shot above was taken from urxvt which doesn’t support faint text colors, otherwise the color of green used for debug messages would have differed slightly from the color of green used for spam messages.

Apart from the faint style of the spam level, the default configuration of coloredlogs sticks to the eight color palette defined by the original ANSI standard, in order to provide a somewhat consistent experience across terminals and terminal emulators.

Available text styles and colors

Of course you are free to customize the default configuration, in this case you can use any text style or color that you know is supported by your terminal. You can use the humanfriendly --demo command to try out the supported text styles and colors:

Screen shot of the 'humanfriendly --demo' command.

Changing the log format

The simplest customization is to change the log format, for example:

$ export COLOREDLOGS_LOG_FORMAT='[%(hostname)s] %(asctime)s %(message)s'
$ coloredlogs --demo
[peter-mbp] 2018-01-14 15:45:44 message with level spam (5)
[peter-mbp] 2018-01-14 15:45:45 message with level debug (10)
[peter-mbp] 2018-01-14 15:45:46 message with level verbose (15)
[peter-mbp] 2018-01-14 15:45:47 message with level info (20)
[peter-mbp] 2018-01-14 15:45:48 message with level notice (25)
[peter-mbp] 2018-01-14 15:45:49 message with level warning (30)
[peter-mbp] 2018-01-14 15:45:50 message with level success (35)
[peter-mbp] 2018-01-14 15:45:51 message with level error (40)
[peter-mbp] 2018-01-14 15:45:52 message with level critical (50)

Here’s what that looks like in a terminal (I always work in terminals with a black background and white text):

Screen shot of colored logging with custom log format.

Changing the date/time format

You can also change the date/time format, for example you can remove the date part and leave only the time:

$ export COLOREDLOGS_LOG_FORMAT='%(asctime)s - %(message)s'
$ coloredlogs --demo
15:45:34 - message with level spam (5)
15:45:35 - message with level debug (10)
15:45:36 - message with level verbose (15)
15:45:37 - message with level info (20)
15:45:38 - message with level notice (25)
15:45:39 - message with level warning (30)
15:45:40 - message with level success (35)
15:45:41 - message with level error (40)
15:45:42 - message with level critical (50)

Here’s what it looks like in a terminal:

Screen shot of colored logging with custom date/time format.

Changing the colors/styles

Finally you can customize the colors and text styles that are used:

$ export COLOREDLOGS_LOG_FORMAT='%(asctime)s - %(message)s'
$ export COLOREDLOGS_FIELD_STYLES='' # no styles
$ export COLOREDLOGS_LEVEL_STYLES='spam=22;debug=28;verbose=34;notice=220;warning=202;success=118,bold;error=124;critical=background=red'
$ coloredlogs --demo
15:45:23 - message with level spam (5)
15:45:24 - message with level debug (10)
15:45:25 - message with level verbose (15)
15:45:26 - message with level info (20)
15:45:27 - message with level notice (25)
15:45:28 - message with level warning (30)
15:45:29 - message with level success (35)
15:45:30 - message with level error (40)
15:45:31 - message with level critical (50)

Here’s an explanation of the features used here:

  • The numbers used in $COLOREDLOGS_LEVEL_STYLES demonstrate the use of 256 color mode (the numbers refer to the 256 color mode palette which is fixed).
  • The success level demonstrates the use of a text style (bold).
  • The critical level demonstrates the use of a background color (red).

Of course none of this can be seen in the shell transcript quoted above, but take a look at the following screen shot:

Screen shot of colored logging with custom colors.

Some notes about log levels

With regards to the handling of log levels, the coloredlogs package differs from Python’s logging module in two aspects:

  1. While the logging module uses the default logging level logging.WARNING, the coloredlogs package has always used logging.INFO as its default log level.

  2. When logging to the terminal or system log is initialized by install() or enable_system_logging() the effective level [1] of the selected logger [2] is compared against the requested level [3] and if the effective level is more restrictive than the requested level, the logger’s level will be set to the requested level (this happens in adjust_level()). The reason for this is to work around a combination of design choices in Python’s logging module that can easily confuse people who aren’t already intimately familiar with it:

    • All loggers are initialized with the level logging.NOTSET.
    • When a logger’s level is set to logging.NOTSET the getEffectiveLevel() method will fall back to the level of the parent logger.
    • The parent of all loggers is the root logger and the root logger has its level set to logging.WARNING by default (after importing the logging module).

    Effectively all user defined loggers inherit the default log level logging.WARNING from the root logger, which isn’t very intuitive for those who aren’t already familiar with the hierarchical nature of the logging module.

    By avoiding this potentially confusing behavior (see #14, #18, #21, #23 and #24), while at the same time allowing the caller to specify a logger object, my goal and hope is to provide sane defaults that can easily be changed when the need arises.


    Refer to logging.Logger.getEffectiveLevel() for details.


    The logger that is passed as an argument by the caller or the root logger which is selected as a default when no logger is provided.


    The log level that is passed as an argument by the caller or the default log level logging.INFO when no level is provided.

Classes and functions

coloredlogs.DEFAULT_LOG_LEVEL = 20

The default log level for coloredlogs (logging.INFO).

coloredlogs.DEFAULT_LOG_FORMAT = '%(asctime)s %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s'

The default log format for ColoredFormatter objects (a string).

coloredlogs.DEFAULT_DATE_FORMAT = '%Y-%m-%d %H:%M:%S'

The default date/time format for ColoredFormatter objects (a string).

coloredlogs.CHROOT_FILES = ['/etc/debian_chroot']

A list of filenames that indicate a chroot and contain the name of the chroot.

coloredlogs.CAN_USE_BOLD_FONT = True

Whether bold fonts can be used in default styles (a boolean).

This is disabled on Windows because in my (admittedly limited) experience the ANSI escape sequence for bold font is simply not translated by Colorama, instead it’s printed to the terminal without any translation.

coloredlogs.DEFAULT_FIELD_STYLES = {'hostname': {'color': 'magenta'}, 'programname': {'color': 'cyan'}, 'name': {'color': 'blue'}, 'levelname': {'color': 'black', 'bold': True}, 'asctime': {'color': 'green'}}

Mapping of log format names to default font styles.

coloredlogs.DEFAULT_LEVEL_STYLES = {'info': {}, 'notice': {'color': 'magenta'}, 'verbose': {'color': 'blue'}, 'success': {'color': 'green', 'bold': True}, 'spam': {'color': 'green', 'faint': True}, 'critical': {'color': 'red', 'bold': True}, 'error': {'color': 'red'}, 'debug': {'color': 'green'}, 'warning': {'color': 'yellow'}}

Mapping of log level names to default font styles.


Automatically call install() when $COLOREDLOGS_AUTO_INSTALL is set.

The coloredlogs package includes a path configuration file that automatically imports the coloredlogs module and calls auto_install() when the environment variable $COLOREDLOGS_AUTO_INSTALL is set.

This function uses coerce_boolean() to check whether the value of $COLOREDLOGS_AUTO_INSTALL should be considered True.

coloredlogs.install(level=None, **kw)[source]

Enable colored terminal output for Python’s logging module.


The coloredlogs.install() function is similar to logging.basicConfig(), both functions take a lot of optional keyword arguments but try to do the right thing by default:

  1. If reconfigure is True (it is by default) and an existing StreamHandler is found that is connected to either stdout or stderr the handler will be removed. This means that first calling logging.basicConfig() and then calling coloredlogs.install() will replace the stream handler instead of adding a duplicate stream handler. If reconfigure is False and an existing handler is found no further steps are taken (to avoid installing a duplicate stream handler).
  2. A StreamHandler is created and connected to the stream given by the stream keyword argument (sys.stderr by default). The stream handler’s level is set to the value of the level keyword argument.
  3. A ColoredFormatter is created if the isatty keyword argument allows it (or auto-detection allows it), otherwise a normal Formatter is created. The formatter is initialized with the fmt and datefmt keyword arguments (or their computed defaults).
  4. HostNameFilter.install() and ProgramNameFilter.install() are called to enable the use of additional fields in the log format.
  5. If the logger’s level is too restrictive it is relaxed (refer to notes about log levels for details).
  6. The formatter is added to the handler and the handler is added to the logger.

Increase the verbosity of the root handler by one defined level.

Understands custom logging levels like defined by my verboselogs module.


Decrease the verbosity of the root handler by one defined level.

Understands custom logging levels like defined by my verboselogs module.


Check whether the log level of the root handler is set to a verbose level.

Returns:True if the root handler is verbose, False if not.

Get the logging level of the root handler.

Returns:The logging level of the root handler (an integer) or DEFAULT_LOG_LEVEL (if no root handler exists).

Set the logging level of the root handler.

Parameters:level – The logging level to filter on (an integer or string).

If no root handler exists yet this automatically calls install().

coloredlogs.adjust_level(logger, level)[source]

Increase a logger’s verbosity up to the requested level.

  • logger – The logger to change (a Logger object).
  • level – The log level to enable (a string or number).

This function is used by functions like install(), increase_verbosity() and enable_system_logging() to adjust a logger’s level so that log messages up to the requested log level are propagated to the configured output handler(s).

It uses logging.Logger.getEffectiveLevel() to check whether logger propagates or swallows log messages of the requested level and sets the logger’s level to the requested level if it would otherwise swallow log messages.

Effectively this function will “widen the scope of logging” when asked to do so but it will never “narrow the scope of logging”. This is because I am convinced that filtering of log messages should (primarily) be decided by handlers.


Find the defined logging levels.

Returns:A dictionary with level names as keys and integers as values.

Here’s what the result looks like by default (when no custom levels or level names have been defined):

>>> find_defined_levels()
{'NOTSET': 0,
 'DEBUG': 10,
 'INFO': 20,
 'WARN': 30,
 'WARNING': 30,
 'ERROR': 40,
 'FATAL': 50,
 'CRITICAL': 50}

Coerce a logging level name to a number.

Parameters:value – A logging level (integer or string).
Returns:The number of the log level (an integer).

This function translates log level names into their numeric values. The logging module does this for us on Python 2.7 and 3.4 but fails to do so on Python 2.6 which coloredlogs still supports.


Find log level names which are aliases of each other.

Returns:A dictionary that maps aliases to their canonical name.


Canonical names are chosen to be the alias with the longest string length so that e.g. WARN is an alias for WARNING instead of the other way around.

Here’s what the result looks like by default (when no custom levels or level names have been defined):

>>> from coloredlogs import find_level_aliases
>>> find_level_aliases()
coloredlogs.parse_encoded_styles(text, normalize_key=None)[source]

Parse text styles encoded in a string into a nested data structure.

Parameters:text – The encoded styles (a string).
Returns:A dictionary in the structure of the DEFAULT_FIELD_STYLES and DEFAULT_LEVEL_STYLES dictionaries.

Here’s an example of how this function works:

>>> from coloredlogs import parse_encoded_styles
>>> from pprint import pprint
>>> encoded_styles = 'debug=green;warning=yellow;error=red;critical=red,bold'
>>> pprint(parse_encoded_styles(encoded_styles))
{'debug': {'color': 'green'},
 'warning': {'color': 'yellow'},
 'error': {'color': 'red'},
 'critical': {'bold': True, 'color': 'red'}}

Find the host name to include in log messages.

Parameters:use_chroot – Use the name of the chroot when inside a chroot? (boolean, defaults to True)
Returns:A suitable host name (a string).

Looks for CHROOT_FILES that have a nonempty first line (taken to be the chroot name). If none are found then socket.gethostname() is used as a fall back.


Select a suitable program name to embed in log messages.

Returns:One of the following strings (in decreasing order of preference):
  1. The base name of the currently running Python program or script (based on the value at index zero of sys.argv).
  2. The base name of the Python executable (based on sys.executable).
  3. The string ‘python’.
coloredlogs.replace_handler(logger, match_handler, reconfigure)[source]

Prepare to replace a handler.


A tuple of two values:

  1. The matched Handler object or None if no handler was matched.
  2. The Logger to which the matched handler was attached or the logger given to replace_handler().

coloredlogs.find_handler(logger, match_handler)[source]

Find a (specific type of) handler in the propagation tree of a logger.

  • logger – The logger to check (a Logger object).
  • match_handler – A callable that receives a Handler object and returns True to match a handler or False to skip that handler and continue searching for a match.

A tuple of two values:

  1. The matched Handler object or None if no handler was matched.
  2. The Logger object to which the handler is attached or None if no handler was matched.

This function finds a logging handler (of the given type) attached to a logger or one of its parents (see walk_propagation_tree()). It uses the undocumented handlers attribute to find handlers attached to a logger, however it won’t raise an exception if the attribute isn’t available. The advantages of this approach are:

  • This works regardless of whether coloredlogs attached the handler or other Python code attached the handler.
  • This will correctly recognize the situation where the given logger has no handlers but propagate is enabled and the logger has a parent logger that does have a handler attached.
coloredlogs.match_stream_handler(handler, streams=[])[source]

Identify stream handlers writing to the given streams(s).

  • handler – The Handler class to check.
  • streams – A sequence of streams to match (defaults to matching stdout and stderr).

True if the handler is a StreamHandler logging to the given stream(s), False otherwise.

This function can be used as a callback for find_handler().


Walk through the propagation hierarchy of the given logger.

Parameters:logger – The logger whose hierarchy to walk (a Logger object).
Returns:A generator of Logger objects.


This uses the undocumented logging.Logger.parent attribute to find higher level loggers, however it won’t raise an exception if the attribute isn’t available.

class coloredlogs.ColoredFormatter(fmt=None, datefmt=None, level_styles=None, field_styles=None)[source]

Log Formatter that uses ANSI escape sequences to create colored logs.


If you want to use ColoredFormatter on Windows then you may need to call colorama.init(). This is done for you when you call coloredlogs.install().

__init__(fmt=None, datefmt=None, level_styles=None, field_styles=None)[source]

Initialize a ColoredFormatter object.


This initializer uses colorize_format() to inject ANSI escape sequences in the log format string before it is passed to the initializer of the base class.


Rewrite a logging format string to inject ANSI escape sequences.

Parameters:fmt – The log format string.
Returns:The logging format string with ANSI escape sequences.

This method takes a logging format string like the ones you give to logging.Formatter, splits it into whitespace separated tokens and then processes each token as follows:

It looks for %(...) field names in the token (from left to right). For each field name it checks if the field name has a style defined in the field_styles dictionary. The first field name that has a style defined determines the style for the complete token.

As an example consider the default log format (DEFAULT_LOG_FORMAT):

%(asctime)s %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s

The default field styles (DEFAULT_FIELD_STYLES) define a style for the name field but not for the process field, however because both fields are part of the same whitespace separated token they’ll be highlighted together in the style defined for the name field.


Apply level-specific styling to log records.

Parameters:record – A LogRecord object.
Returns:The result of logging.Formatter.format().

This method injects ANSI escape sequences that are specific to the level of each log record (because such logic cannot be expressed in the syntax of a log format string). It works by making a copy of the log record, changing the msg field inside the copy and passing the copy into the format() method of the base class.

formatTime(record, datefmt=None)[source]

Format the date/time of a log record.


The formatted date/time (a string).

This method overrides formatTime() to set datefmt to DEFAULT_DATE_FORMAT when the caller hasn’t specified a date format.

class coloredlogs.Empty[source]

An empty class used to copy LogRecord objects without reinitializing them.

class coloredlogs.HostNameFilter(use_chroot=True)[source]

Log filter to enable the %(hostname)s format.

Python’s logging module doesn’t expose the system’s host name while I consider this to be a valuable addition. Fortunately it’s very easy to expose additional fields in format strings: filter() simply sets the hostname attribute of each LogRecord object it receives and this is enough to enable the use of the %(hostname)s expression in format strings.

You can install this log filter as follows:

>>> import coloredlogs, logging
>>> handler = logging.StreamHandler()
>>> handler.addFilter(coloredlogs.HostNameFilter())
>>> handler.setFormatter(logging.Formatter('[%(hostname)s] %(message)s'))
>>> logger = logging.getLogger()
>>> logger.addHandler(handler)
>>> logger.setLevel(logging.INFO)
>>>"Does it work?")
[peter-macbook] Does it work?

Of course coloredlogs.install() does all of this for you :-).

classmethod install(handler, fmt=None, use_chroot=True)[source]

Install the HostNameFilter on a log handler (only if needed).

  • handler – The logging handler on which to install the filter.
  • fmt – The log format string to check for %(hostname).
  • use_chroot – Refer to find_hostname().

If fmt is given the filter will only be installed if fmt contains %(programname). If fmt is not given the filter is installed unconditionally.


Initialize a HostNameFilter object.

Parameters:use_chroot – Refer to find_hostname().

Set each LogRecord’s hostname field.

class coloredlogs.ProgramNameFilter(programname=None)[source]

Log filter to enable the %(programname)s format.

Python’s logging module doesn’t expose the name of the currently running program while I consider this to be a useful addition. Fortunately it’s very easy to expose additional fields in format strings: filter() simply sets the programname attribute of each LogRecord object it receives and this is enough to enable the use of the %(programname)s expression in format strings.

Refer to HostNameFilter for an example of how to manually install these log filters.

classmethod install(handler, fmt, programname=None)[source]

Install the ProgramNameFilter (only if needed).

  • fmt – The log format string to check for %(programname).
  • handler – The logging handler on which to install the filter.
  • programname – Refer to __init__().

Initialize a ProgramNameFilter object.

Parameters:programname – The program name to use (defaults to the result of find_program_name()).

Set each LogRecord’s programname field.

class coloredlogs.StandardErrorHandler(level=0)[source]

A StreamHandler that gets the value of sys.stderr for each log message.

The StandardErrorHandler class enables monkey patching of sys.stderr. It’s basically the same as the logging._StderrHandler class present in Python 3 but it will available regardless of Python version. This handler is used by coloredlogs.install() to improve compatibility with the Python standard library.


Initialize a StandardErrorHandler object.


Get the value of sys.stderr (a file-like object).

class coloredlogs.NameNormalizer[source]

Responsible for normalizing field and level names.


Initialize a NameNormalizer object.


Normalize a field or level name.

Parameters:name – The field or level name (a string).
Returns:The normalized name (a string).

Transforms all strings to lowercase and resolves level name aliases (refer to find_level_aliases()) to their canonical name:

>>> from coloredlogs import NameNormalizer
>>> from humanfriendly import format_table
>>> nn = NameNormalizer()
>>> sample_names = ['DEBUG', 'INFO', 'WARN', 'WARNING', 'ERROR', 'FATAL', 'CRITICAL']
>>> print(format_table([(n, nn.normalize_name(n)) for n in sample_names]))
| DEBUG    | debug    |
| INFO     | info     |
| WARN     | warning  |
| WARNING  | warning  |
| ERROR    | error    |
| FATAL    | critical |
| CRITICAL | critical |

Normalize the keys of a dictionary using normalize_name().

Parameters:value – The dictionary to normalize.
Returns:A dictionary with normalized keys.
get(normalized_dict, name)[source]

Get a value from a dictionary after normalizing the key.

  • normalized_dict – A dictionary produced by normalize_keys().
  • name – A key to normalize and get from the dictionary.

The value of the normalized key (if any).

The coloredlogs.converter module

Convert text with ANSI escape sequences to HTML.

coloredlogs.converter.capture(command, encoding='UTF-8')[source]

Capture the output of an external command as if it runs in an interactive terminal.

  • command – The command name and its arguments (a list of strings).
  • encoding – The encoding to use to decode the output (a string).

The output of the command.

This function runs an external command under script (emulating an interactive terminal) to capture the output of the command as if it was running in an interactive terminal (including ANSI escape sequences).

coloredlogs.converter.convert(text, code=True, tabsize=4)[source]

Convert text with ANSI escape sequences to HTML.

  • text – The text with ANSI escape sequences (a string).
  • code – Whether to wrap the returned HTML fragment in a <code>...</code> element (a boolean, defaults to True).
  • tabsize – Refer to str.expandtabs() for details.

The text converted to HTML (a string).

coloredlogs.converter.encode_whitespace(text, tabsize=4)[source]

Encode whitespace so that web browsers properly render it.

  • text – The plain text (a string).
  • tabsize – Refer to str.expandtabs() for details.

The text converted to HTML (a string).

The purpose of this function is to encode whitespace in such a way that web browsers render the same whitespace regardless of whether ‘preformatted’ styling is used (by wrapping the text in a <pre>...</pre> element).


While the string manipulation performed by this function is specifically intended not to corrupt the HTML generated by convert() it definitely does have the potential to corrupt HTML from other sources. You have been warned :-).


Replace runs of multiple spaces with non-breaking spaces.

Parameters:match – A regular expression match object.
Returns:The replacement string.

This function is used by func:encode_whitespace() as a callback for replacement using a regular expression pattern.


Encode characters with a special meaning as HTML.

Parameters:text – The plain text (a string).
Returns:The text converted to HTML (a string).

Convert a CSS color in hexadecimal notation into its R, G, B components.

Parameters:value – A CSS color in hexadecimal notation (a string like ‘#000000’).
Returns:A tuple with three integers (with values between 0 and 255) corresponding to the R, G and B components of the color.
Raises:ValueError on values that can’t be parsed.
coloredlogs.converter.select_text_color(r, g, b)[source]

Choose a suitable color for the inverse text style.

  • r – The amount of red (an integer between 0 and 255).
  • g – The amount of green (an integer between 0 and 255).
  • b – The amount of blue (an integer between 0 and 255).

A CSS color in hexadecimal notation (a string).

In inverse mode the color that is normally used for the text is instead used for the background, however this can render the text unreadable. The purpose of select_text_color() is to make an effort to select a suitable text color. Based on

class coloredlogs.converter.ColoredCronMailer[source]

Easy to use integration between coloredlogs and the UNIX cron daemon.

By using ColoredCronMailer as a context manager in the command line interface of your Python program you make it trivially easy for users of your program to opt in to HTML output under cron: The only thing the user needs to do is set CONTENT_TYPE="text/html" in their crontab!

Under the hood this requires quite a bit of magic and I must admit that I developed this code simply because I was curious whether it could even be done :-). It requires my capturer package which you can install using pip install 'coloredlogs[cron]'. The [cron] extra will pull in the capturer 2.4 or newer which is required to capture the output while silencing it - otherwise you’d get duplicate output in the emails sent by cron.


Initialize output capturing when running under cron with the correct configuration.


Start capturing output (when applicable).

__exit__(exc_type=None, exc_value=None, traceback=None)[source]

Stop capturing output and convert the output to HTML (when applicable).


Tell __exit__() to swallow all output (things will be silent).

This can be useful when a Python program is written in such a way that it has already produced output by the time it becomes apparent that nothing useful can be done (say in a cron job that runs every few minutes :-p). By calling silence() the output can be swallowed retroactively, avoiding useless emails from cron.

The coloredlogs.syslog module

Easy to use UNIX system logging for Python’s logging module.

Admittedly system logging has little to do with colored terminal output, however:

  • The coloredlogs package is my attempt to do Python logging right and system logging is an important part of that equation.
  • I’ve seen a surprising number of quirks and mistakes in system logging done in Python, for example including %(asctime)s in a format string (the system logging daemon is responsible for adding timestamps and thus you end up with duplicate timestamps that make the logs awful to read :-).
  • The %(programname)s filter originated in my system logging code and I wanted it in coloredlogs so the step to include this module wasn’t that big.
  • As a bonus this Python module now has a test suite and proper documentation.

So there :-P. Go take a look at enable_system_logging().

coloredlogs.syslog.LOG_DEVICE_MACOSX = '/var/run/syslog'

The pathname of the log device on Mac OS X (a string).

coloredlogs.syslog.LOG_DEVICE_UNIX = '/dev/log'

The pathname of the log device on Linux and most other UNIX systems (a string).

coloredlogs.syslog.DEFAULT_LOG_FORMAT = '%(programname)s[%(process)d]: %(levelname)s %(message)s'

The default format for log messages sent to the system log (a string).

The %(programname)s format requires ProgramNameFilter but enable_system_logging() takes care of this for you.

The name[pid]: construct (specifically the colon) in the format allows rsyslogd to extract the $programname from each log message, which in turn allows configuration files in /etc/rsyslog.d/*.conf to filter these log messages to a separate log file (if the need arises).

class coloredlogs.syslog.SystemLogging(*args, **kw)[source]

Context manager to enable system logging.

__init__(*args, **kw)[source]

Initialize a SystemLogging object.


Enable system logging when entering the context.

__exit__(exc_type=None, exc_value=None, traceback=None)[source]

Disable system logging when leaving the context.


If an exception is being handled when we leave the context a warning message including traceback is logged before system logging is disabled.

coloredlogs.syslog.enable_system_logging(programname=None, fmt=None, logger=None, reconfigure=True, **kw)[source]

Redirect logging messages to the system log (e.g. /var/log/syslog).


A SysLogHandler object or None. If an existing handler is found and reconfigure is False the existing handler object is returned. If the connection to the system logging daemon fails None is returned.


When the logger’s effective level is too restrictive it is relaxed (refer to notes about log levels for details).

coloredlogs.syslog.connect_to_syslog(address=None, facility=None, level=None)[source]

Create a SysLogHandler.


A SysLogHandler object or None (if the system logging daemon is unavailable).

The process of connecting to the system logging daemon goes as follows:

  • If SysLogHandler supports the socktype option (it does since Python 2.7) the following two socket types are tried (in decreasing preference):

    1. SOCK_RAW avoids truncation of log messages but may not be supported.
    2. SOCK_STREAM (TCP) supports longer messages than the default (which is UDP).
  • If socket types are not supported Python’s (2.6) defaults are used to connect to the selected address.


Find the most suitable destination for system log messages.

Returns:The pathname of a log device (a string) or an address/port tuple as supported by SysLogHandler.

On Mac OS X this prefers LOG_DEVICE_MACOSX, after that LOG_DEVICE_UNIX is checked for existence. If both of these device files don’t exist the default used by SysLogHandler is returned.


Identify system logging handlers.

Parameters:handler – The Handler class to check.
Returns:True if the handler is a SysLogHandler, False otherwise.

This function can be used as a callback for find_handler().