# colout: colour any command output with a regular expression

> colout is a small command line tool that reads text on standard input and paints the parts matching a regular expression, in colours you name or in ones it derives from the text itself, from a hash of the match to a position on a numeric scale. It also ships themes for common tool output and can act as a front end for Pygments.

**nojhan/colout** — Color text streams with a polished command line interface

- Repository: https://github.com/nojhan/colout
- Website: http://nojhan.github.io/colout/
- Stars: 1,162 · Forks: 59
- Language: Python
- License: GPL-3.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/nojhan-colout

## A stream filter, not a wrapper

colout reads lines of a text stream on standard input and outputs characters matching a given regular expression in a given colour and style. The synopsis is the whole interface:

```
colout [-g] [-c] [-l min,max] [-a] [-t] [-T DIR] [-P DIR] [-d COLORMAP] [-s] [-e CHAR] [-E CHAR] [--debug] PATTERN [COLOR(S) [STYLE(S)]]
```

The shape of that is the shape of a Unix filter. The pattern and the colour are positional, everything else is a switch, and the program does not care what produced the text on standard input. That is the design decision, and it is the one that makes the tool composable. A pipeline that ends in colout gets colour, and anything before it in the pipeline can stay unchanged.

The Python re module defines the regular expression dialect, and the README says so explicitly, which is worth noting because the pattern is the part of the interface a user will actually fight with.

The defaults are conservative in a useful way. When a colour is not specified it defaults to red, and when a style is not specified it defaults to bold. So the shortest useful invocation is a pattern and nothing else, and it is hard to end up with output that is technically coloured but unreadable.

There is a second synopsis for the resource listing, colout -r, which prints the available resources instead of filtering anything.

## Colours you name, and colours it derives

The colour vocabulary is long, and the interesting part is the set of special colormaps that derive a colour from the matched text itself.

The named colours are the familiar ones, blue, black, yellow, cyan, green, magenta, white and red, plus none, an RGB hexadecimal triplet such as #11aaff, and any number between 0 and 255. Styles cover normal, bold, faint, italic, underline, blink, rapid_blink, reverse, conceal and random, with the honest caveat that some styles may have no effect depending on your terminal.

Foreground and background are combined with a period, so red.blue means red on blue, and the same syntax combines two styles, bold.blink. The -e and -E switches change the separators, which matters if your data itself contains dots or commas.

The derived colormaps are the distinctive part. rainbow cycles over the default colormap at each match, and Rainbow does the same in 256-colour mode. Random picks a random colour for each match among the ANSI table, while random does it in 8-colour mode, and spectrum and Spectrum are like rainbows with more colours, 8 and 36.

scale and Scale are more useful than they sound. They parse the numeric characters in the matched text as a decimal number, taking your locale into account, or even as an arithmetic expression such as 1+2/0.9*3, and apply the colormap according to the position of that number on a scale defined by the -l option, 0 to 100 by default. That turns a log of measurements into a heat map. hash and Hash take a fingerprint of the matched text instead, so the same text always gets the same colour, which is what you want when the same identifier appears repeatedly in a log.

Before interpreting a match as a number, colout removes every character that cannot be part of one, which lets you colour a whole group while only the numerical part drives the colour.

## Groups, multiple colours, and how the mismatches resolve

The rules for capture groups are the part of the interface that decides whether a pattern is usable, and the README states them precisely.

If groups are specified in the regular expression, only they are taken into account. Otherwise the whole matching pattern is coloured. That is a meaningful difference for a log filter, because colouring the whole match includes the text you were not looking for.

You can specify several colours or several styles when using groups, by separating them with commas. Two resolution rules then apply. If you indicate more colours than there are groups, the last ones are ignored. If you ask for fewer colours than there are groups, the last one is duplicated across the remaining groups.

The second rule is the friendlier one, because it means a two-group pattern with a single colour still colours both groups, so a common case does not need the colour repeated.

The -g switch interacts with the colormaps. For colour maps like rainbow, it iterates over the matching groups in the pattern instead of over the patterns, which is what you want when a single match contains several fields that should get different colours from the same map.

The -a switch changes the unit of work. By default the input is coloured line by line, and with --all the whole input is coloured at once, which the README says is really useful for colouring a source code file with strings spanning multiple lines. The -c switch supplies a custom colormap as a comma-separated list of colours, cycled at each match.

## Themes, Pygments lexers and GIMP palettes

colout has three ways to be told what colour means, and they cover most of what a person would want.

The first is a theme. The -t switch interprets the pattern as a predefined theme, with perm, cmake and g++ given as examples, and -T DIR searches for additional themes, which are colout_*.py files. The themes are the fastest way to get useful colour for a well-known output format without writing a pattern, and the presence of a themes release tag, v1.1b, in the release history shows they were a deliberate feature rather than an afterthought.

The second is Pygments. The -s switch interprets the pattern as source code readable by the Pygments library, with a neat convention: if the first letter of the pattern is upper case you get the 256-colour mode and if it is lower case you get 8 colours, and in 256-colour mode the colour is read as a Pygments style such as default. The README also says colout can be used as an interface to Pygments, with the --source switch, and that the name of a Pygments lexer can be used as a colour, for example Cpp, ruby or xml+django.

The third is palettes. If GIMP palette files, .gpl, are available their names can be used as a colormap, found through the -P DIR switch.

The catch is colour fidelity. RGB colours, whether given as hex triplets or taken from a palette, are converted to their nearest ANSI 256-colour equivalents. So a palette that looks right in an image editor will look approximate in the terminal, and the README warns that an external palette used as the default colormap will not work with a special colormap in 8-colour mode.

## Installing it, and the routes that have aged

The recommended installation is a pip install for the local user:

```console
$ pip install --user colout
```

The alternatives are documented with their status, which is unusual and useful. A pipsi install is offered, with the note that pipsi is no longer maintained. And there is a PPA for Ubuntu 16.04 and 18.04 at version 0.6.1-3~dist7, marked as not actively maintained, installed with:

```console
$ sudo add-apt-repository ppa:csaba-kertesz/random
$ sudo apt-get update
$ sudo apt-get/aptitude install colout
```

The pip route is the one to use, and the version numbers in the other two routes are the reason. The PPA is pinned to Ubuntu releases that are long out of support and to a version of colout from before the themes work, so a user on a current distribution who follows the older instructions ends up with a much older build.

The packaging itself is conventional. The setup.py declares a single package, colout, with the console script entry point colout=colout.colout:main, requires pygments and babel, and derives the version from git with setuptools_scm through use_scm_version. The classifiers say Development Status 5 - Production/Stable, list Python 3.5 through 3.8, and mark the licence as GPLv3, and there is a tox.ini and a requirements-build.txt for development.

## Where colout is the wrong choice

The first wrong-tool case is syntax highlighting of source code. That is Pygments' job, and colout's own --source mode is a thin front end to it. A tool that wraps a better tool is worth it when the wrapper saves you a step, and here it saves you one flag, which is not much.

The second is output that never reaches standard output. colout reads a stream, so anything written to a terminal directly, to a log file, or to a progress bar that redraws in place is invisible to it. A tool that colours a build system's live output is fighting the wrong layer.

The third is a terminal you do not control. The colour model is ANSI escape sequences, and the README is careful that some styles may have no effect depending on the terminal, and that the 256-colour modes need a terminal that supports those escape sequences. On a minimal terminal emulator, on some CI log viewers, and over a serial console, the result is escape sequences visible as literal characters or as nothing at all. The -d option warns about a related trap, that a default colormap incompatible with the special colormap's mode will not produce the colours you expect.

There is also the age of the project to weigh. The newest release tag is v1.1b from 2023, the version classifiers stop at Python 3.8, and the last push was in June 2026, so the repository is touched but the distribution is not recently refreshed. A tool that filters text has a long life, but a long-lived tool on an old release deserves a version check before it lands in a script that runs unattended.

## GPL-3.0, a 2023 release, and a tool that still composes

colout is released under the GNU General Public License v3, with the LICENSE file at the repository root, and the project description is as plain as the tool's name suggests, color up arbitrary command output.

The release history is short. The versions are v1.1b, described as themes, from 2023-02-14, and v1.0, whose name is a small joke about the arrival of colour, from 2022-05-12. There are no GitHub releases beyond those tags, the default branch is master, and the last push was on 2026-06-14.

So the picture is a mature, small, stable tool that gets occasional attention rather than regular releases. The repository layout matches that: a colout/ package, a tox.ini for testing across environments, a requirements-build.txt, a MANIFEST.in, a .travis.yml, and an example.gdbinit, which is a GDB script and hints at the intended audience, people who work in a terminal all day and want their logs to be legible.

The design has aged well, because it depends on nothing that has changed. A regular expression, ANSI escapes and a pipe are stable interfaces, and the special colormaps, scale and hash in particular, are the kind of small idea that keeps being useful years after it was written.

## Conclusion

Adopt colout if you spend time reading command output and want the important parts of it to stand out, particularly if you script pipelines where a highlighted warning or an error line needs to be seen at a glance. Do not adopt it as a syntax highlighter, since Pygments already does that, and do not expect it to colour output that never reaches standard output, because it only reads a stream. Before you rely on it, check that your terminal supports the escape sequences you intend to use, since the README notes that some styles have no effect depending on the terminal, and pin a version, because the newest tag is from 2023 and the Python version classifiers stop at 3.8.

## FAQ

### How do I install colout?

The recommended method is pip install --user colout. The README also documents a pipsi install, noting that pipsi is no longer maintained, and an Ubuntu PPA for 16.04 and 18.04 at version 0.6.1-3~dist7 which is marked as not actively maintained.

### What colours can colout use?

Named colours such as red, blue, green, cyan, magenta, yellow, black and white, plus none, an RGB hexadecimal triplet such as #11aaff, and any number from 0 to 255. You can also use the name of a Pygments lexer as a colour, or the name of a colour in a GIMP palette file.

### What do the scale and hash colour maps do in colout?

scale and Scale parse the numeric characters of the match as a decimal number or an arithmetic expression and apply the colormap according to the number's position on the scale set by the -l option, 0 to 100 by default. hash and Hash take a fingerprint of the matched text, so the same text always gets the same colour.

### How does colout handle capture groups and several colours?

If groups are specified in the pattern only they are coloured, otherwise the whole match is. Several colours or styles are separated by commas, and if you give more colours than groups the last ones are ignored, while if you give fewer the last colour is duplicated across the remaining groups.

### What licence is colout released under?

GNU General Public License v3, with the LICENSE file at the repository root and the same licence named in the package classifiers. The most recent release is v1.1b, dated 2023-02-14, and the last push was on 2026-06-14.

## Sources

- [License: GPL-3.0](https://github.com/nojhan/colout/blob/master/LICENSE)
- [nojhan/colout on GitHub](https://github.com/nojhan/colout)
- [Project website](http://nojhan.github.io/colout/)
- [README](https://github.com/nojhan/colout/blob/master/README.md)
- [Releases](https://github.com/nojhan/colout/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nojhan-colout