Convert a Netpbm Image to QOI with pamtoqoi

pamtoqoi turns any Netpbm image into a QOI file in one pass, and this guide covers converting it and verifying the header. Round-trip it back afterwards to prove nothing was lost. Give it about ten minutes.

The examples were tested with Netpbm 11.5.2, from Debian package netpbm 2:11.05.02-1.1build1. You need a shell, an input image in a Netpbm format, and write access to the destination directory. The conversion is an ordinary unprivileged command; do not reach for sudo just because a conversion failed, and only use it if the input or destination is deliberately locked down.

1. Check the installed command

Confirm which binary will run and record the local Netpbm version, this changes nothing on disk:

$ command -v pamtoqoi
/usr/bin/pamtoqoi
$ pamtoqoi --version
pamtoqoi: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The extra lines from --version are build information, not image output. Keep this check well away from an actual conversion, QOI is binary data and should never land in your terminal.

2. Inspect the input before converting

Swap in a real path for /path/to/input.ppm. pamtoqoi reads a Netpbm image and writes QOI, nothing more; there is no resize, crop or colour-adjustment option hiding in it. Checking the input first tells you quickly whether a problem is the source or the conversion:

$ pamfile /path/to/input.ppm
/path/to/input.ppm: Netpbm PPM "rawbits" image data, 640 by 480

Exact pamfile wording depends on the input and installed tools. A non-zero status, an unreadable path or an unexpected size is your cue to fix the source before you bother making QOI from it.

There are no pamtoqoi-specific image options here. The manual lists only the common libnetpbm options, notably -quiet. Option names can be abbreviated, but full names audit better in scripts.

3. Write a new QOI file

Pick a destination with nothing valuable in it yet:

$ pamtoqoi /path/to/input.ppm > /path/to/output.qoi
$ test -s /path/to/output.qoi && echo 'QOI output is non-empty'
QOI output is non-empty

The input argument is optional. Leave it out and pamtoqoi reads standard input, so a pipeline works just as well:

$ cat /path/to/input.ppm | pamtoqoi > /path/to/output.qoi

Never pipe the QOI stream to your terminal. It is binary, and stray control bytes can make the display look broken even when the file itself is perfectly fine.

$ cp --preserve=all /path/to/output.qoi /path/to/output.qoi.bak
$ pamtoqoi /path/to/input.ppm > /path/to/output.qoi.new
$ test -s /path/to/output.qoi.new && mv /path/to/output.qoi.new /path/to/output.qoi

If conversion fails, leave the original alone and go find out why. Remove an unwanted temporary file only after double-checking its path. The backup can be deleted once the replacement has been opened and checked, that deletion is a separate, irreversible action, so do not fold it into the same command line.

4. Verify the QOI header and dimensions

QOI's header carries width, height, channel count and colourspace. The system file command reads enough of it for a quick, independent check:

$ file /path/to/output.qoi
/path/to/output.qoi: QOI image data 640x480, sRGB (linear alpha)

Dimensions and wording should closely match your input. The exact description depends on your file version and the QOI channel and colourspace fields. A non-empty file on its own is not proof you encoded the image you meant to.

QOI is lossless, but a clean encoder exit still will not tell you that you pointed it at the right input. Keep the original around until dimensions and visual result have both been checked.

5. Round-trip back to Netpbm

The installed companion command, qoitopam, decodes QOI back to a Netpbm PAM stream. Write it to a clearly named file and inspect it:

$ qoitopam /path/to/output.qoi > /path/to/roundtrip.pam
$ pamfile /path/to/roundtrip.pam
/path/to/roundtrip.pam: Netpbm PAM image file, size = 640 x 480

That confirms format and dimensions, it is not a substitute for opening the image in a trusted viewer when visual correctness actually matters. If qoitopam errors out, keep the original input and QOI file, capture the diagnostic, and check that a QOI encoder actually produced the file rather than something that wrote text or an error message to your destination by mistake.

Nothing persistent changes in this workflow. Recovery just means abandoning the new QOI file and keeping the original Netpbm image. If you used the .new pattern, the old output is still sitting there until the final mv.

6. Troubleshoot the likely distractions

• Cannot open input: check the path and read permission with ls -l and test -r /path/to/input.ppm. Do not add sudo before you have confirmed the path.
• Empty or missing output: check the shell exit status right away with printf 'status: %s\n' "$?", then check the destination directory and available space.
• Unexpected dimensions: run pamfile on both source and round-trip files. pamtoqoi never resizes the image.
• Unreadable output: use file and qoitopam. Do not infer validity from a plausible filename or a successful-looking redirection.
• Permission error at the destination: write to a directory you own, then move the finished file through your normal controlled deployment process if one applies.