PIXterm: drawing images in the terminal with true color and half blocks

An image, rendered out of coloured cells

PIXterm shows images directly in your terminal. The technique is worth understanding before using the tool, because it explains both what the output looks like and why the requirements are what they are.

The pixels are recreated through a combination of ANSI character background colour and the unicode lower half block element. A terminal cell is a rectangle, and a single character with a background colour fills only the top or bottom half of it, so pairing a foreground colour with a background colour lets one cell carry two vertically stacked pixels. That halves the vertical resolution compared with one cell per pixel, and it is the reason a photograph looks recognisable rather than like a mosaic of separate squares.

When the image has transparency, an optional matte colour is used for the background, which is the standard trick for compositing an image with an alpha channel onto a flat colour instead of onto whatever the terminal happens to be showing.

You can also specify a dithering mode, and then the image is rendered using block elements with different shades, or using standard ASCII characters in the same way. In dithering mode the matte colour is used to fill the background of the blocks or characters.

The conversion process runs fast because it is parallelised in all CPUs, which is the answer to the obvious objection that decoding and quantising an image in a script would be slow. The supported formats are JPEG, PNG, GIF, BMP, TIFF and WebP, and fetching images from HTTP and HTTPS URLs is supported as well, so the tool is usable as a one-liner against a URL.

The project describes itself as a terminal toy application made to exercise the author's Go skills, and it is honest about that. The repository is not archived, and the version in the README banner is 1.3.3.

Three rendering modes, and the -nobg flag

The documentation is organised around the rendering modes, and the screenshots are grouped the same way, which tells you how much the output varies between them.

The first group is the classic mode, no dithering, where the image is drawn with the half block trick and true colour. This is the best looking mode and the default.

The second group is dithering with blocks, where the image is rendered using block elements of different shades. The relevant characters are the full block and the three shading levels, so a font has to include four specific glyphs for this mode to work.

The third group is dithering with characters, which uses standard ASCII characters in the same way. Since it relies only on ASCII, this mode works with any font, which is why it exists as a separate mode rather than as a variation.

The fourth group is dithering with the background colour disabled, which the documentation labels with the -nobg flag. The screenshots in that group are the ones to look at if you want to see what the output looks like in a terminal where the background colour would clash with the image, and the contributor list credits the original code for disabling the background colour in dithering mode.

The choice between the modes is a trade between fidelity and compatibility. True colour with half blocks is the most accurate rendering, but it needs a terminal with true color support and a font with the lower half block glyph. Dithering sacrifices colour accuracy for a much wider range of terminals and fonts, and the ASCII character mode is the last fallback for a terminal that cannot do colour at all.

True color and a monospaced font, both required

The requirements section is short and unforgiving, and it is the first thing to read.

Your terminal emulator must support the true color feature, or the image colours will not be displayed correctly. In addition you must use a monospaced font that includes the lower half block unicode character, U+2584. The author recommends Envy Code R, and it is the font shown in the screenshots. If you want the dithering mode with blocks, the font must also include the full block U+2588 and the three shading characters U+2593, U+2592 and U+2591. The dithering mode with characters works with standard ASCII characters.

Both requirements are about the same underlying fact. The renderer assumes a grid of identical rectangular cells and it uses colour and glyph shape to encode pixels. A terminal that cannot do true colour collapses the colour dimension, and a proportional font destroys the grid, because the characters would not line up in columns and the reconstructed image would be skewed.

The practical failure modes are worth predicting for yourself. On a terminal with a sixteen colour palette the image will look roughly right but muddy, since similar colours get collapsed into the same palette entry. On a font without the half block glyph you will get a missing character box where the top half of every cell should be, and the picture will look like a row of small underlines. Neither failure announces itself, so a quick check of the font before you rely on the tool saves some confusion.

The monospaced requirement is also why this belongs in a terminal rather than a log file. The output is a grid of coloured characters, and it only means something when something interprets the colour codes.

Installing with go install, and the AUR route

The requirement is the Go compiler, version 1.25 or higher, installed on your system. Everything else comes through the standard Go module system, and the documentation is emphatic that you should not do anything else.

The install command downloads the sources and places the PIXterm binary in your $GOPATH/bin directory, or $GOBIN if you set it:

go install github.com/eliukblau/pixterm/cmd/pixterm@latest

On Arch Linux there is an AUR package, and the documentation credits Fabius for creating it. The install command given is:

yaourt -S pixterm

There is a warning attached to that. A previous package called pixterm-git, created by eigengrau, is now orphaned and the documentation says not to use it. If you have that package installed from an older guide, that is the package to remove.

For local development the repository root has two commands, and the CLI is built from the cmd/ directory:

# run
go run ./cmd/pixterm

# build
go build -o path/for/binary ./cmd/pixterm

The build target is the piece to copy if you want a static binary for another machine, and the go run form is the one to use while you are changing the code, since it compiles and launches in a single step.

The ANSImage package behind the CLI

The repository is split into cmd/ and pkg/, and the pkg/ tree holds the ANSImage package, which is the part other Go programs can import. The README documents its dependencies separately from the CLI's.

For the CLI the dependencies are go-colorful and the terminal package. For the ANSImage package they are go-colorful, the imaging package, and the WebP, BMP and TIFF decoders from golang.org/x/image.

The go.mod file is the precise version of that list. The module requires Go 1.25.0, and it pulls in disintegration/imaging at v1.6.2, lucasb-eyer/go-colorful at v1.4.0, golang.org/x/image at v0.38.0 and golang.org/x/term at v0.42.0, with golang.org/x/sys at v0.43.0 as an indirect dependency.

The discrepancy between the two lists is small but real. The README names golang.org/x/crypto/ssh/terminal for the CLI, while the manifest uses golang.org/x/term, which is the package that superseded it. The manifest is the authoritative statement of what the build actually uses, and the contributor list credits MichaelMure with a more conventional go.mod file at the repository, which is probably when that changed.

The imaging dependency is the one doing the real work of resizing. The ANSImage API exposes constructors such as NewFromImage and NewScaledFromImage, contributed by diamondburned, and the scaling is what allows an image of arbitrary size to fit the cell grid of a terminal. Without it you would have to pre-size every image by hand before displaying it.

Formats, URLs and where the idea came from

The feature list is short and complete: six image formats, HTTP and HTTPS fetching, and a parallelised conversion. GIF is in the format list, which is interesting given that an animated GIF has many frames, and the documentation does not say whether animation is played or whether you get the first frame.

The image download support is credited to HongjiangHuang in the contributor list, and the transparency handling to @disq, with a later fix by @timob for the ANSIpixel type to use an 8 bit colour component for output, which is a small detail that matters for terminal output efficiency since 24 bit colour triples the bytes per cell. The Windows colour support for Command Prompt and PowerShell, and the code that outputs the image through fmt.Print(), are credited to @brutestack, and the update of very old dependencies to @grisu48.

The provenance is documented too, which is unusual in a project of this size. The application is described as inspired by termpix, implemented in Rust, and the dithering mode is the author's own port of the render from the Processing Textmode Engine.

The licence is the Mozilla Public License Version 2.0, and the licence file is LICENSE.txt at the repository root. MPL-2.0 is a file-level copyleft licence, which is a reasonable choice for a small tool whose code you might vendor into a larger project while keeping your own changes to it open.

The release history explains the version gaps. v1.3.1 was tagged on 2019-12-27, v1.3.2 on 2024-09-15 and v1.3.3 on 2026-08-01, with the last push on the same day as the newest tag. So the project has picked up again after a long quiet period, and the current line is the one the README describes.

Editorial conclusion

Adopt PIXterm if you want to look at an image from a terminal over SSH, in a CI log, or on a machine with no display, and you accept that the result is an approximation made of coloured cells. Do not adopt it if you need the original image, since the output is a raster approximation limited by the terminal's cell grid, and do not expect it to look right in a terminal without true color support or with a proportional font. Before you start, check that your terminal supports true color and that your font includes the lower half block character, install with go install github.com/eliukblau/pixterm/cmd/pixterm@latest if your Go toolchain is 1.25 or newer, and use the dithering modes only as a fallback since a true color terminal gives the better result.

Frequently asked questions

Official sources

1. eliukblau/pixterm on GitHub
2. Issues
3. License: MPL-2.0
4. README
5. Releases