Turn a PPM Image into Coloured ASCII with ppmtoascii

You will turn a PPM image into an ASCII preview that can be displayed in an ANSI-capable terminal. The command reads a PPM file, reduces its pixels into character-sized groups, and writes the result to standard output with terminal colour control sequences. Allow about ten minutes if the PPM already exists. The examples below use Netpbm 11.5.2, installed from Debian's netpbm package.

This is a read-only conversion. It does not alter the source image, and it does not need elevated privileges when you can read the input and write to your current directory.

1. Check the installed command

Confirm that the executable is available and record the version before relying on it in a script:

$ command -v ppmtoascii
/usr/bin/ppmtoascii
$ ppmtoascii --version
ppmtoascii: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
ppmtoascii: Built from source dated 2024-03-31 09:09:47

The manual page describes the command as part of Netpbm and documents a much older interface, updated in 2010. The installed version is the behaviour verified here. If your version differs, check man ppmtoascii before putting an option into a long-lived script.

2. Convert a PPM file to terminal output

Pass the input file as the optional positional argument:

$ ppmtoascii /path/to/image.ppm

The output contains ordinary ASCII characters mixed with ANSI escape sequences. In a terminal that understands those sequences, you should see a small, rough coloured rendering. The exact characters and colours depend on the image. ANSI provides only eight colours, including black and white, so this is a preview rather than a faithful image conversion.

When a character represents several pixels with different colours, the terminal cannot colour each pixel separately. The command uses an average colour for that character. This is why fine detail and colour boundaries can look approximate even when the PPM is valid.

3. Choose the pixel grouping

By default, ppmtoascii uses -1x2. Each output character represents one pixel across by two pixels down. For a denser result, use -2x4, which represents two pixels across by four pixels down:

$ ppmtoascii -1x2 /path/to/image.ppm
$ ppmtoascii -2x4 /path/to/image.ppm

The second mode normally produces fewer characters, so it is useful when a large image would scroll beyond the terminal. It also throws away more spatial detail. These options describe how input pixels are grouped; neither option resizes the PPM file and neither changes the source.

The spelling matters. The documented forms are -1x2 and -2x4, with the first one being the default. A misspelled option is rejected rather than silently ignored.

4. Keep the output on screen, or capture it deliberately

For a quick preview, leave standard output attached to the terminal. If you need to pipe it to another command, remember that the stream includes ANSI control characters:

$ ppmtoascii -2x4 /path/to/image.ppm | less -R

The -R option tells this common pager to pass through recognised colour sequences. Availability and behaviour of less are separate from Netpbm, so omit the pipe if it is not installed.

Do not treat the result as a new PPM file. ppmtoascii is one-way, and its output is text intended for a terminal. Redirecting it creates a text file containing escape codes and ASCII art, not a portable image:

$ ppmtoascii -2x4 /path/to/image.ppm > image-ascii.txt
$ sed -n '1,5p' image-ascii.txt

Opening that file in a terminal may show colour, while opening it in a text editor will usually show visible escape notation or odd spacing. Use a new destination name when redirecting. Shell > truncates an existing file before the command starts.

$ rm -- image-ascii.txt

That removal is irreversible. No sudo is needed for files in a directory you own.

5. Use standard input in a pipeline

The filename is optional, so a PPM can come from standard input. This is useful when another Netpbm command produces a temporary image stream:

$ pnmcrop /path/to/image.ppm | ppmtoascii -2x4

This example requires pnmcrop, which is a separate Netpbm program. The important boundary is that ppmtoascii consumes PPM input and writes terminal-oriented output. It does not preserve the original PPM as an intermediate file.

For a safe local test without an image file, feed it a tiny plain PPM:

$ printf 'P3\n2 2\n255\n255 0 0 0 255 0\n0 0 255 255 255 255\n' | ppmtoascii -1x2
[terminal output includes ANSI colour sequences]

The displayed characters may look different when your terminal handles the escape sequences, but a successful run should return to the shell without an error. To check the exit status immediately, use:

$ printf 'P3\n2 2\n255\n255 0 0 0 255 0\n0 0 255 255 255 255\n' | ppmtoascii -1x2 > /dev/null
$ printf '%s\n' "$?"
0

6. Diagnose the common failures

If the input cannot be opened, check the path and read permission without changing anything:

$ ls -l /path/to/image.ppm
$ test -r /path/to/image.ppm && echo readable

If the input is not a valid PPM, inspect its header with a tool that can identify it, then fix or regenerate the source. Do not rename another image format to .ppm and expect the extension to convert it.

If the terminal output is too large, retry with -2x4. If it is too coarse, use the default -1x2. If you see raw sequences beginning with characters such as ^[ or ESC, use an ANSI-aware terminal or pager. The command itself is still producing the documented control characters.

For a quiet invocation, Netpbm's common options include -quiet, but the rendered ASCII output is still the command's purpose. Do not use quiet mode as a way to remove colour codes. Check the installed manual for common-option details if you are writing a script.