Convert a QOI Image to PAM with qoitopam

You will convert a QOI image into a Netpbm image, normally a PAM file, and verify that the result is readable. qoitopam writes the converted image to standard output, so a shell redirection or pipe decides where the result goes. Allow about ten minutes if the input file is already available.

This guide uses the installed Netpbm package version 2:11.05.02-1.1build1, which provides Netpbm 11.05.02 on this machine. You need a readable QOI file and a shell. The conversion itself normally needs no elevated privileges. Do not use sudo merely because the command deals with an image.

1. Check the installed command

Confirm that the shell will run the expected binary and record the package version. These are ordinary read-only checks:

$ command -v qoitopam
/usr/bin/qoitopam
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The manual page has a slightly confusing name in its generated NAME section, where it describes pamtoqoi. The command and synopsis are clear: qoitopam reads QOI and produces a Netpbm image. The installed command accepts one optional input file. With no input-file argument, it reads standard input.

2. Convert a QOI file to a new output

Replace /path/to/input.qoi with the path to your image. Choose a new destination name so the first test cannot overwrite an existing result:

$ qoitopam /path/to/input.qoi > converted.pam
$ printf 'exit status: %s\n' "$?"
exit status: 0

A successful exit status means that qoitopam completed the conversion. It does not by itself prove that you chose the intended input or that the image looks right. The input is read, not modified.

Shell redirection is the part most likely to cause an avoidable mistake. The > operator truncates converted.pam before the program starts. If the named output already contains something useful, use a temporary name and promote it only after checking it:

$ qoitopam /path/to/input.qoi > converted.pam.new
$ file converted.pam.new
converted.pam.new: Netpbm PAM image file, size = 1 x 1
$ mv -- converted.pam.new converted.pam

The dimensions in the example are only illustrative. Your file output should report the dimensions of your input. If conversion fails, remove the incomplete converted.pam.new after checking that it is the temporary file you meant to discard. The original converted.pam remains in place because the final mv was not run.

3. Verify the Netpbm output

Use file as a quick format and dimensions check:

$ file converted.pam
converted.pam: Netpbm PAM image file, size = WIDTH x HEIGHT

The exact wording varies with the file package. The useful evidence is that the result is identified as a Netpbm PAM image and has the expected dimensions. If pamfile is installed, it can inspect the Netpbm header in more detail:

$ pamfile converted.pam
converted.pam: P7  WIDTH HEIGHT 3 255 RGB

Replace the uppercase placeholders in the displayed examples with the numbers printed by your machine; they are not literal output. Keep the original QOI file until you have opened or further converted the PAM image. PAM is an interchange format, so a later Netpbm command can read it without changing the source image.

4. Feed QOI through standard input

Use a pipe when another program produces QOI or when you do not want to pass a file name as the input argument:

$ cat /path/to/input.qoi | qoitopam > converted.pam
$ file converted.pam
converted.pam: Netpbm PAM image file, size = WIDTH x HEIGHT

The same command can be written with shell input redirection:

$ qoitopam < /path/to/input.qoi > converted.pam

These forms have the same important boundary: QOI enters through standard input and PAM leaves through standard output. Avoid mixing diagnostic text into the output stream. If a wrapper needs to log messages, keep logs on standard error and reserve the redirected standard output for the image.

5. Use quiet mode only when needed

The only documented options are common Netpbm options, notably -quiet. It suppresses ordinary messages, which can help when a script expects image bytes on standard output:

$ qoitopam -quiet /path/to/input.qoi > converted.pam
$ printf 'exit status: %s\n' "$?"
exit status: 0

-quiet does not repair a bad QOI file and does not change the output format. Keep it out of the first manual test if you need diagnostics. The manual also permits option abbreviations, but full option names make scripts easier to review. No image dimensions, resize options or output-file option are documented for qoitopam; do not invent them. Choose the output path with shell redirection.

6. Diagnose a failed conversion

For an input error, first check the path and read permission without changing anything:

$ ls -l /path/to/input.qoi
$ test -r /path/to/input.qoi && echo readable
readable

If the command reports an invalid QOI image, preserve the original and inspect the input with the program that created it or with a trusted QOI-aware tool. A file with a .qoi suffix is not proof that its contents are valid. Do not run the converter as root to bypass a permission error; fix access to the specific input and output paths instead.

If the command returns a non-zero status after redirection, the destination may be empty or partial. Check it before reusing the name:

$ file converted.pam
$ test -s converted.pam && echo 'output is non-empty'

When replacing an existing output, the temporary-name workflow in step 2 is the recovery path. Remove only the known temporary file, then rerun the conversion after correcting the input. There is no persistent service or configuration change to undo.