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.
thumbnailenables PNG thumbnail generation and its ICO/PNG codecs.clienables theicoextractandicolistbinaries. Combine it withthumbnailto enableexe-thumbnailer.
For a dependency, enable optional features as needed:
[]
= { = "0.1", = ["thumbnail"] }
For a local checkout, the same feature combinations are available with Cargo:
Library usage
use ;
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 ;
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.