Convert a PCX File to PPM with pcxtoppm

Old scanner software and DOS-era paint programs left PCX files everywhere, and pcxtoppm turns one into a PPM you can actually work with. Examples here match the installed Netpbm 11.5.2 command from package version 2:11.05.02-1.1build1.

Allow about ten minutes. You need a readable PCX file, a shell, and enough free space for the uncompressed PPM output. Conversion itself needs no elevated privileges; skip sudo unless ordinary file permissions are genuinely in your way.

1. Check the installed command

Confirm which executable will run and note the local Netpbm version. Both are read-only checks:

$ command -v pcxtoppm
/usr/bin/pcxtoppm
$ pcxtoppm -version 2>&1 | head -4
pcxtoppm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pcxtoppm: Built from source dated 2024-03-31 09:09:47
pcxtoppm: Built by Debian

The command takes an optional PCX filename and writes the PPM image to standard output. That output stream is the one detail worth remembering: a successful run doesn't create a file unless you redirect it yourself.

2. Check the input before converting

Inspect the file without touching it. Swap in the path to your own image:

$ INPUT='/path/to/image.pcx'
$ test -r "$INPUT" && echo 'input is readable'
input is readable
$ file "$INPUT"
/path/to/image.pcx: PCX ... image data ...

The exact file description varies with the PCX variant. pcxtoppm supports colormapped files with 2 to 16 colours, 256-colour files, 24-bit truecolour files, and 32-bit files with an intensity plane. A file can still be damaged even when its name and initial type look plausible, so keep the original around until you've checked the converted image.

If that test produces no output, the file isn't readable by your current user. Fix the path or the permissions deliberately; don't jump to root access as a diagnostic shortcut.

3. Convert to a new PPM path

Choose a destination that isn't holding anything you care about. Shell redirection truncates an existing destination before pcxtoppm even starts, so this example uses a fresh filename:

$ OUTPUT='/path/to/image.ppm'
$ pcxtoppm "$INPUT" > "$OUTPUT"
$ printf 'exit status: %s\n' "$?"
exit status: 0

Exit status 0 means the converter finished; it doesn't guarantee the image looks right. If the command fails, the redirected file may be empty or incomplete. Only remove or rename it after confirming it's the new file, not your original PCX or a previous good PPM.

There's no persistent configuration to undo here. To discard a conversion you no longer need, check the exact path before deleting the generated PPM, and leave the PCX source untouched.

4. Verify the PPM header and dimensions

Use file or Netpbm's pamfile to inspect the result:

$ file "$OUTPUT"
/path/to/image.ppm: Netpbm image data, size 640 x 480, rawbits, pixmap
$ pamfile "$OUTPUT"
/path/to/image.ppm: PPM raw, 640 by 480  maxval 255

Your own wording may differ slightly. Look for a PPM result, non-zero dimensions, and dimensions that match the source PCX. A raw PPM normally opens with the magic number P6, followed by width, height and maximum channel value:

$ head -3 "$OUTPUT"
P6
640 480
255

Only the header is text. Everything after it is binary pixel data, so don't open the whole file in a text editor or rely on a full cat to inspect it.

5. Use diagnostics when the result is unexpected

Pass -verbose to see the PCX header details pcxtoppm actually decoded. Keep the image output redirected separately, because diagnostic text lands on the terminal:

$ pcxtoppm -verbose "$INPUT" > "$OUTPUT"
pcxtoppm: Version: 3
pcxtoppm: BitsPerPixel: 8
pcxtoppm: Planes: 1    BytesPerLine: 640    PaletteInfo: 1

The values depend entirely on the file. This mode is useful for telling a 16-colour packed or bitplane image apart from a 256-colour or truecolour one. If the header describes a different format from what you expected, inspect the original file and whatever produced it, rather than forcing a guessed option.

pcxtoppm has no resize option. Its output dimensions come straight from the PCX image bounds, so a wrong size usually points to malformed input or a format this version simply doesn't recognise.

6. Handle a misleading 16-colour palette

-stdpalette makes pcxtoppm use its predefined standard palette even when a 16-colour PCX supplies its own. That's specifically useful when an old or limited producer wrote a random palette into the file instead of a meaningful one:

$ pcxtoppm -stdpalette "$INPUT" > /path/to/image-standard-palette.ppm
$ pamfile /path/to/image-standard-palette.ppm
/path/to/image-standard-palette.ppm: PPM raw, 640 by 480  maxval 255

Don't reach for this option by habit. It only matters for the 16-colour paletted format. On a valid file with a deliberate custom palette, swapping the palette out changes the colours and can make the result less accurate. Compare the normal and standard-palette outputs in an image viewer whenever a source's palette is in doubt.

7. Convert a batch without destroying earlier output

For multiple files, write each result to a temporary name in the same directory, verify it, then rename it into place. That keeps a previous PPM available if a conversion goes wrong:

$ pcxtoppm /path/to/image.pcx > /path/to/image.ppm.new
$ pamfile /path/to/image.ppm.new
/path/to/image.ppm.new: PPM raw, 640 by 480  maxval 255
$ mv /path/to/image.ppm.new /path/to/image.ppm

That final mv replaces an existing destination on the same filesystem, so treat it as deliberate and check both paths before running it. If validation fails, leave the old output alone and remove only the specifically named .new file during your normal cleanup; never reach for a broad wildcard with rm.