Convert Windows Icons to PAM Images with winicontopam

You will turn a Microsoft Windows icon file into a Netpbm PAM image, inspect the selected image and keep transparency available for later processing. This guide uses the installed Netpbm 11.5.2 command. Allow about ten minutes. You need a shell, a readable .ico file and the netpbm package. The conversion is normally unprivileged and does not modify the input.

1. Check the installed command

Confirm which executable your shell will run and record its version:

$ command -v winicontopam
$ winicontopam --version

On the system used for this guide, the command reports Netpbm Version 11.5.2, built by Debian from source dated 2024-03-31. The version matters when you are comparing output from another machine, because image decoding details can vary between releases.

You do not need sudo for a file in your home directory or another location you can read. Use elevated privileges only when the operating system genuinely requires them to read the input or write the chosen output directory. Do not use root merely because the input came from Windows.

2. Convert the default image

Run the converter with the path to your icon and redirect standard output to a new PAM file:

$ winicontopam /path/to/icon.ico > icon.pam

By default, winicontopam extracts one image: the best-quality entry, meaning the largest image first and then the one with the most bits per pixel. The output is a multi-image PAM stream even when the stream contains only one image. The normal output is binary, so do not expect useful text after the command prompt returns.

Verify the file with Netpbm's PAM inspector:

$ pamfile icon.pam

A successful result identifies the file as PAM and reports its width, height, depth and maximum value. A typical RGBA icon has depth 4 and tuple type RGB_ALPHA. For example, a 16 by 16 test icon produced:

/tmp/icon.pam:    PAM, 16 by 16 by 4 maxval 255
    Tuple type: RGB_ALPHA

Your dimensions and tuple type depend on the selected icon entry. A successful exit status alone does not prove that you selected the image you wanted, so check these properties before passing the file to another tool.

3. Select a particular icon entry

Icon files often contain several sizes and encodings. Image numbers start at zero. Select an entry explicitly with -image:

$ winicontopam -image=0 /path/to/icon.ico > icon-0.pam
$ pamfile icon-0.pam

This is useful when a program needs a known size rather than the command's quality choice. The index is the position in the icon file, not a pixel dimension. If you need to discover which entries exist, make a copy of the source for investigation and use the verbose output:

$ winicontopam -verbose /path/to/icon.ico > icon.pam

The diagnostic text is written to the terminal while the PAM data remains redirected to the file. Read the reported image details and then choose an index for a reproducible conversion. Keep the original icon unchanged while deciding.

4. Export every image

Use -allimages when you need every entry rather than one selected image:

$ winicontopam -allimages /path/to/icon.ico > icon-all.pam
$ pamfile icon-all.pam

The result is a multi-image PAM file. To create one file per image, split that stream with pamsplit:

$ mkdir -p icon-frames
$ pamsplit icon-all.pam -output=icon-frames/frame-%d.pam
$ find icon-frames -maxdepth 1 -type f -print

The exact filenames depend on the pamsplit options installed on your system, so treat the final find command as the check that files were created. The mkdir changes state only by creating the named directory. To undo that change after checking the results, remove the directory and its generated files deliberately, for example rm -r icon-frames; that deletion is irreversible.

5. Keep or expose both transparency forms

Windows icons can carry an old-style AND mask, a graded transparency map, or both. The converter uses graded transparency when present and otherwise uses the AND mask for the PAM transparency plane. PNG-encoded entries and 32-bit BMP entries can carry graded transparency.

If you need the AND mask as well as graded transparency, request it explicitly:

$ winicontopam -andmasks /path/to/icon.ico > icon-with-mask.pam
$ pamfile icon-with-mask.pam

When both forms exist, the output has five channels and the AND mask is the fifth plane. The option has no effect when the graded data is formally present but contains only opaque pixels. Do not assume that a four-channel output contains the original mask separately.

6. Avoid the common failures

Do not combine -image and -allimages. They describe conflicting selection policies, and the installed command rejects the combination:

$ winicontopam -image=0 -allimages /path/to/icon.ico > failed.pam
winicontopam: You cannot specify both -allimages and -image

If the input is not a Windows icon, the command reports that it is not a valid Windows icon file and writes no PAM image. Check the file type and path without changing the source:

$ file /path/to/icon.ico
$ ls -l /path/to/icon.ico

A redirection target is opened before the converter runs. Therefore, > icon.pam truncates an existing file even if conversion later fails. Use a new name such as icon.pam.new, inspect it with pamfile, and then make any replacement explicit. If it is incomplete, remove only that temporary file.

Option names can be abbreviated to a shortest unique prefix, and either one or two hyphens are accepted. Full names are safer in scripts and easier for another operator to review. Values can follow an equals sign or whitespace, but the documented forms above avoid ambiguity.