Create a Windows ICO File from PPM Images with ppmtowinicon

ppmtowinicon packs one or more PPM images into a Windows .ico file, mask support and all, while leaving your source images untouched. Allow about ten minutes if the PPM files are already prepared. You need the Netpbm package and a shell. The examples use Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1.

1. Check the installed command

Confirm the executable is available before scripting a batch job:

$ command -v ppmtowinicon
/usr/bin/ppmtowinicon
$ ppmtowinicon -version
ppmtowinicon: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
ppmtowinicon: Built from source dated 2024-03-31 09:09:47

The version output gives build details rather than a short version number. If the command is missing, install Netpbm through your normal package-management process. Neither conversion nor verification normally needs sudo; reach for elevated access only when the input or destination directory is deliberately restricted.

2. Convert one PPM image

Pass a PPM file as the final argument and name the destination with -output=:

$ ppmtowinicon -output=icon.ico /path/to/icon.ppm

A successful run is quiet and drops you back at the prompt. The output file is a Windows icon containing the input image; the input filename is a separate argument from the -output= option.

Check both the exit status and the file type:

$ test -s icon.ico && echo "icon created"
icon created
$ file icon.ico
icon.ico: MS Windows icon resource - 1 icon, 16x1, 16 colors, 4 bits/pixel

The exact wording from file depends on the image and the installed file database. Look for an MS Windows icon resource and a non-empty file, not an exact dimensions or colour-depth line.

3. Build a multi-resolution icon

A Windows icon can contain several images, and Windows picks whichever best matches the display's resolution and colour depth. Supply the PPM files in one command, in the order you want them stored:

$ ppmtowinicon \
    -output=app.ico \
    /path/to/app-16x16.ppm \
    /path/to/app-32x32.ppm \
    /path/to/app-48x48.ppm
$ file app.ico
app.ico: MS Windows icon resource - 3 icons

The manual cites 16 x 16 at 4 bits per pixel, 32 x 32 at 4 bits per pixel, and 48 x 48 at 8 bits per pixel as recommended contents for an icon. Those are recommendations, not resizing instructions: ppmtowinicon reads exactly the PPM images you give it. Prepare each resolution with an appropriate Netpbm tool or another trusted image converter first.

Omit the input filename and the command reads PPM data from standard input. Omit -output and it writes ICO data to standard output, useful in a pipeline:

$ cat /path/to/app-16x16.ppm | ppmtowinicon > app.ico
$ test -s app.ico && file app.ico

Do not use a text-oriented command such as tee or an editor to inspect the binary output. Use file or an icon-aware viewer.

4. Add a transparency mask

For transparent icons, add -andpgms. Each image must then be followed by its matching PGM mask, so the arguments come in pairs:

$ ppmtowinicon -andpgms -output=app-transparent.ico \
    /path/to/app.ppm /path/to/app-mask.pgm
$ file app-transparent.ico

The mask is a standard Netpbm PGM file. A pixel that is completely opaque in the mask is opaque in the icon; every other mask value counts as transparent. ICO files have no partial translucency through this interface. A PBM file is also accepted as the mask and treated like a PGM.

With -andpgms alone, the usual non-opaque behaviour can merge foreground and background bits, producing a reverse-video effect when the foreground is not black. Add -truetransparent for ordinary transparency instead:

$ ppmtowinicon -andpgms -truetransparent \
    -output=app-transparent.ico \
    /path/to/app.ppm /path/to/app-mask.pgm

The option name in the synopsis is -andpgms. Do not substitute the -andmask wording that shows up in the manual's explanatory text; use the option listed under the command's actual options.

5. Avoid overwriting an existing icon

$ cp --preserve=all app.ico app.ico.backup
$ ppmtowinicon -output=app.ico.new /path/to/app.ppm
$ test -s app.ico.new && file app.ico.new
app.ico.new: MS Windows icon resource - 1 icon, ...
$ mv app.ico.new app.ico

6. Diagnose a bad result

An input error usually means a path, permission or PPM-format problem. Check the source without changing it:

$ ls -l /path/to/app.ppm /path/to/app-mask.pgm
$ test -r /path/to/app.ppm && echo "PPM readable"
$ head -n 3 /path/to/app.ppm

For an ordinary PPM, the header identifies the format and dimensions; do not rely on the filename extension. If you are using masks, confirm every image has exactly one following mask, since a missing or misordered pair can produce an unusable icon even when the command accepts the input.

If the icon displays with the wrong background effect, rerun with -truetransparent. If it contains the wrong resolution, check the dimensions of the source PPMs and rebuild the icon with the intended files. Keep the source images and masks until the icon has been checked in the application that will use it.