Convert a Netpbm Image to QOI with pamtoqoi

You will finish with a QOI file made from a Netpbm image, a checked round trip back to Netpbm, and a safer way to choose the output path. The examples were tested with Netpbm 11.5.2, from Debian package netpbm 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, an input image in a Netpbm format, and write access to the destination directory. The conversion itself is an ordinary unprivileged command. Do not use sudo unless the input or destination is deliberately restricted, and do not grant it merely because a conversion failed.

1. Check the installed command

Confirm which executable will run and record the local Netpbm version. This changes nothing:

$ 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 separate from a conversion, because QOI is binary data and should not be allowed into your terminal.

2. Inspect the input before converting

Use a real path in place of /path/to/input.ppm. pamtoqoi reads a Netpbm image and writes QOI; it does not provide a resize, crop or colour-adjustment option. Inspecting first helps separate an input problem from a conversion problem:

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

The exact pamfile wording varies with the input and installed tools. A non-zero status, an unreadable path or an unexpected size is a reason to fix the source file before creating QOI.

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

3. Write a new QOI file

Choose a destination that does not already contain valuable data:

$ 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. Without it, pamtoqoi reads standard input, so a pipeline is also valid:

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

Do not pipe the QOI stream to the terminal. QOI is binary, and terminal control bytes can make the display confusing even when the file is correct.

$ 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 in place and investigate the error. Remove an unwanted temporary file only after checking its path. Once the replacement has been opened and checked, the backup may be deleted as a separate, irreversible action.

4. Verify the QOI header and dimensions

The QOI format has a header containing the width, height, channel count and colourspace. The system file command can read enough of that header to provide a quick independent check:

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

The dimensions and wording should match your input closely. The exact description depends on the file utility and the QOI channel and colourspace fields. A non-empty file alone is not proof that the intended image was encoded.

QOI is lossless, but a successful encoder exit still does not tell you that you selected the right input. Keep the original until the dimensions and visual result have been checked.

5. Round-trip back to Netpbm

The installed companion command, qoitopam, decodes QOI to a Netpbm PAM stream. Write that stream to a temporary or clearly named file, then 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

This is a useful format and dimension check. It does not replace opening the image in a trusted viewer when visual correctness matters. If qoitopam reports an error, keep the original input and QOI file, capture the diagnostic, and check that the file was produced by a QOI encoder rather than by a command that wrote text or an error message to the destination.

No persistent configuration changed in this workflow. Recovery is simply to stop using the new QOI file and retain the original Netpbm image. If you used the .new pattern, the old output remains available 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 confirming the path.
• Empty or missing output: inspect the shell exit status immediately with printf 'status: %s\n' "$?", then check the destination directory and available space.
• Unexpected dimensions: run pamfile on both the source and round-trip files. pamtoqoi does not resize the image.
• Unreadable output: use file and qoitopam. Do not infer validity from a plausible filename or from a successful 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 is required.