Create a Windows ICO file from PPM images with ppmtowinicon

You will convert one or more PPM images into a Windows .ico file, check that the file was created, and keep the source images intact. Allow about ten minutes if the PPM files are ready. 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 that the executable is available before preparing a batch command:

$ 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 includes 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; use 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 returns to the shell prompt. The output file is a Windows icon containing the input image. The option takes the output filename after the equals sign, while the input filename is a separate argument.

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 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. Windows chooses the image that 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 the PPM images you provide. Prepare each resolution with an appropriate Netpbm tool or another trusted image converter before this step.

If you omit the input filename, the command reads PPM data from standard input. If you omit -output, it writes the ICO data to standard output. Redirecting to a new filename is useful for 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 are 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 is treated as transparent. ICO files do not provide partial translucency through this interface. A PBM file is also accepted as the mask and is treated like a PGM.

With -andpgms, the usual non-opaque behaviour can merge foreground and background bits, producing a reverse-video effect when the foreground is not black. Add -truetransparent when you want 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 appears in the manual's explanatory text: use the option listed under the command's 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

If conversion fails, leave the original app.ico in place and inspect the error. After you have opened and checked the replacement, remove app.ico.backup only if you no longer need recovery. That deletion cannot be undone from the command line.

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 that every image has exactly one following mask; 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, inspect 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.