Convert a PPM Image to Sixel with ppmtosixel

You will finish with a DEC sixel file generated from a PPM image, with a deliberate choice between compact output and raw pixels. You will also know when to use the -7bit option and how to check the stream without trying to display control codes in an ordinary terminal.

Allow about ten minutes. You need Netpbm's ppmtosixel command and a readable PPM file. This guide uses Netpbm 11.05.02-1.1build1, with the local library reporting Netpbm 11.5.2. Output is terminal or printer control data, not a normal image file for a desktop viewer.

1. Check the installed command

Confirm that the command resolves to the expected executable and record the package version. These are ordinary, read-only checks and do not need elevated privileges:

$ command -v ppmtosixel
/usr/bin/ppmtosixel
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ ppmtosixel --version 2>&1 | head -4
ppmtosixel: Using libnetpbm from Netpbm Version: 11.5.2
ppmtosixel: Built from source dated 2024-03-31 09:09:47

The version output is diagnostic text from this installation rather than a portable interface promise. If your package reports another release, read its local manual before relying on version-specific behaviour. The -7bit option was added in Netpbm 11.04.

2. Convert a PPM file with the normal compact output

Pass the PPM path as the optional final argument and redirect standard output to a new file:

$ ppmtosixel /path/to/input.ppm > /path/to/output.six
ppmtosixel: maxval of input is not the sixel maxval (100) - rescaling to fewer colors
ppmtosixel: computing colormap...
ppmtosixel: 4 colors found

The diagnostic lines may differ with the image. The important result is that sixel bytes went to output.six, while diagnostics went to the terminal. The default output is compressed: adjacent identical pixels can be represented by repeat-pixel commands. That normally makes the file smaller and faster to print.

Checkpoint: verify that the destination exists and is non-empty without displaying it:

$ test -s /path/to/output.six && wc -c /path/to/output.six
83 /path/to/output.six

The byte count depends on the image, so treat the number above as an example rather than a required value. Do not run cat output.six in a terminal unless you intentionally want to send its control sequence to that terminal.

3. Use 7-bit control codes when transport compatibility matters

By default, control codes are emitted as single 8-bit C1 characters. Add -7bit when the file must cross a path that handles only 7-bit C0 controls:

$ ppmtosixel -7bit /path/to/input.ppm > /path/to/output-7bit.six
$ od -An -tx1 -N 16 /path/to/output-7bit.six
 1b 50 30 3b 30 3b 38 71 22 31 3b 31 0a 23 30 3b

This option produces a more portable sixel stream, but it can be larger because a control code may need two 7-bit characters. It does not convert the image to another raster format and it does not make a terminal support sixel.

Checkpoint: keep the two outputs separate and compare their sizes if transport efficiency matters:

$ wc -c /path/to/output.six /path/to/output-7bit.six
 81 /path/to/output.six
 83 /path/to/output-7bit.six
164 total

4. Choose raw output only for a reason

Use -raw when every pixel must be described explicitly:

$ ppmtosixel -raw /path/to/input.ppm > /path/to/output-raw.six
$ test -s /path/to/output-raw.six && wc -c /path/to/output-raw.six
81 /path/to/output-raw.six

For a tiny image the sizes may be similar. On an image with long runs of the same colour, raw output is often an order of magnitude larger than the compressed default and prints more slowly. Do not choose -raw as a debugging habit; compare the files or use it only when the receiving device requires explicit pixels.

You can combine options when needed, for example ppmtosixel -raw -7bit input.ppm > output.six. The options affect the sixel stream, not the source PPM. The input remains untouched.

5. Add a printer margin deliberately

Without -margin, the image starts at the left margin of the window or paper. Add -margin to request a 1.5 inch left margin:

$ ppmtosixel -margin /path/to/input.ppm > /path/to/output-with-margin.six
$ test -s /path/to/output-with-margin.six

The option changes the control data sent to the sixel consumer. It does not crop or resize the PPM. Printer placement can still depend on the printer or terminal, so check a sample before using it for a batch.

6. Understand colour rescaling

Sixel output uses a maximum colour value of 100. If the PPM has another maxval, ppmtosixel rescales the RGB values before constructing its colour assignment table. A common 8-bit PPM therefore triggers a message about rescaling and may lose some least-significant colour detail.

This is a conversion limitation, not a reason to run the command as root. The manual also warns that an LJ250 printer's palette may not match colours shown on screen. If colour accuracy matters, inspect the result on the actual target terminal or printer and keep the original PPM for another conversion.

7. Print or display the result safely

A sixel file must generally reach its printer unfiltered. The manual gives lpr -x or a direct write to a terminal device as examples:

$ lpr -x /path/to/output.six
$ cat /path/to/output.six > /dev/tty0?

The device path is hardware-specific. Do not paste the second command unchanged: replace the placeholder only after identifying the correct device, and make sure you have permission to write to it. A wrong device can disrupt another terminal session. Neither command is needed to create or verify the sixel file.

For recovery, stop using the generated file and remove it only after checking that it is the correct destination. The conversion itself changes no input or system configuration. If a redirect overwrote an existing output file, there is no ppmtosixel undo operation; restore that file from your normal backup or regenerate it from the original PPM.

Common traps

• A successful exit status proves that conversion completed, not that a terminal or printer supports sixel.
• Seeing readable text in the terminal is not an error: the output is control data. Redirect it to a file.
• Do not assume the byte count or colour palette from one image applies to another.
• Keep -7bit separate from -raw: one changes control-code encoding, while the other disables pixel-run compression.
• Do not use sudo to solve a missing input, a bad output path or a device-selection mistake.