icoextract_rs 0.1.2

Cross-platform extraction of icon resources from PE executables
Documentation

icoextract-rs

icoextract-rs is a library-first, cross-platform Rust port of the Python icoextract project. It reads PE32 and PE32+ resource tables from file-layout .exe, .dll, and .mun files, lists their group icons, and exports standard ICO data without Windows APIs.

Features

The default feature set is deliberately small: PE icon extraction only. pelite is an internal PE parser detail and is not exposed through this crate's API.

  • thumbnail enables PNG thumbnail generation and its ICO/PNG codecs.
  • cli enables the icoextract and icolist binaries. Combine it with thumbnail to enable exe-thumbnailer.

For a dependency, enable optional features as needed:

[dependencies]
icoextract-rs = { version = "0.1", features = ["thumbnail"] }

For a local checkout, the same feature combinations are available with Cargo:

cargo test                         # default library
cargo build --features thumbnail   # thumbnail library API
cargo build --features cli         # icoextract and icolist
cargo build --features cli,thumbnail  # all three binaries

Library usage

use icoextract_rs::{IconExtractor, IconSelector};

fn extract() -> icoextract_rs::Result<Vec<u8>> {
    let extractor = IconExtractor::from_path("program.exe")?;
    let icon = extractor.get_icon(IconSelector::Index(0))?;
    icon.to_ico_bytes()
}

IconExtractor::from_path and IconExtractor::from_bytes automatically detect PE inputs. list_group_icons() returns group and frame metadata without copying frame payloads. Use icon_by_index, icon_by_resource_id, or get_icon(IconSelector::Resource(...)) to select an icon; the resource selector accepts u16, &str, and String values. ExtractedIcon::write_ico and IconExtractor::export_icon stream the same standard ICO representation to a writer or path.

On Unix and Windows, from_path retains a read-only memory map rather than eagerly loading and copying the entire executable. This keeps memory use low for multi-gigabyte inputs. from_bytes still copies its input, so the extractor remains independent of a caller-owned buffer.

With the thumbnail feature, create a PNG from the first group icon:

use icoextract_rs::thumbnail::{ThumbnailOptions, generate_thumbnail};

fn thumbnail() -> icoextract_rs::Result<()> {
    generate_thumbnail("program.exe", "program.png", ThumbnailOptions::default())
}

Normal thumbnails follow the reference tool's 128/256 frame-selection policy; ThumbnailOptions::new(size, true) forces an exact square resize.

Command-line tools

Build the commands with --features cli (and additionally thumbnail for the third command), then use:

icoextract [-n NUM] [-i ID] [-v] INPUT OUTPUT
icolist [-v] INPUT
exe-thumbnailer [-s SIZE] [-f] [-v] INPUT OUTPUT

All commands also accept -V/--version. icoextract writes ICO bytes even when OUTPUT has a .png, .jpg, or .jpeg suffix, and emits a warning for that extension. -i takes a decimal numeric resource ID or an exact named resource ID; when omitted, -n selects a zero-based group-icon index.

icolist prints group IDs plus image dimensions, resource RVAs, file offsets, and declared byte sizes. exe-thumbnailer writes PNG and applies the same reference-compatible thumbnail policy as the library API.

Freedesktop thumbnailer

After building exe-thumbnailer, install assets/exe-thumbnailer.thumbnailer in the user thumbnailer directory (often ~/.local/share/thumbnailers/) or the corresponding system thumbnailer directory. Ensure exe-thumbnailer is on PATH. The asset registers the PE MIME types used by the reference project and invokes the binary with %s, %i, and %o.

Error handling

All public parsing and serialization operations return icoextract_rs::Result<T>. Error distinguishes unreadable paths, unrecognized executables, unavailable icons, missing selectors, malformed group resources, corrupt PE data, and invalid ICO output. Inputs are bounds checked; malformed caller data yields an error instead of a panic.

Compatibility

This port reproduces the PE-facing API and behavior of the reference icoextract 0.3.0 project: PE32/PE32+ detection, numeric and named group resources, ICO export, listing metadata, thumbnail behavior, and all three tools. It intentionally does not implement Win16/NE resource extraction. NE headers are detected so the library can return a clear unsupported-format error, but their resource tables are never parsed.