pngtools

A suite of command-line utilities for inspecting and manipulating PNG image files, modelled on libtiff's tifftools. pngtools is packaged by several Linux distributions.

Tools

• pnginfo: Display detailed metadata about PNG files (dimensions, bit depth, colour type, interlacing, compression, text chunks, etc). Supports tiffinfo-compatible output labels (-t) and bitmap dumping (-d, -D).

• pngchunks: List the raw chunk structure of a PNG file by directly parsing chunk headers. Shows chunk type, length, CRC, IHDR fields, and the case-encoded properties of each chunk name.

• pngchunkdesc: Read PNG chunk names from stdin and decode the meaning of each letter's case (critical/ancillary, public/private, PNG 1.2 compliant, safe to copy).

• pngcp: Copy a PNG file while optionally changing the bit depth (-d) and number of samples per pixel (-s).

Packaging status

The badge above (via Repology) shows the pngtools version each distribution currently ships. Find your distribution in the list: green means it is up to date with the current upstream release, red means it is behind. Note that GitHub caches badge images, so the badge can lag the live data on Repology by a while.

Building

Requires libpng-dev and optionally docbook-utils (for man pages):

aclocal && autoconf && automake --add-missing && autoreconf
./configure
make
make install

Usage Examples

# Show PNG metadata
pnginfo image.png

# Show metadata with tiffinfo-compatible labels
pnginfo -t image.png

# Dump image bitmap as hex
pnginfo -d image.png

# List raw chunk structure
pngchunks image.png

# Decode chunk name properties
echo "tEXt" | pngchunkdesc

# Copy with changed bit depth
pngcp -d 16 input.png output.png

Testing

The test suite uses Python testtools + stestr:

# One-time setup
python3 -m venv tests/.venv
tests/.venv/bin/pip install -r test-requirements.txt

# Generate additional test images
tests/.venv/bin/python tests/generate_test_images.py

# Run all tests
tests/.venv/bin/stestr run

# Run a specific test module
tests/.venv/bin/stestr run test_pnginfo

Or use the all-in-one script that handles building and testing (including first-time setup):

scripts/build-and-test.sh

Fuzzing

Coverage-guided fuzz harnesses live in fuzz/ and run in CI: a 60-second smoke test on every PR that touches parsing code, and a 30-minute run per target nightly. See fuzz/README.md for how to build and run them locally.

Pre-commit Hooks

Pre-commit hooks enforce formatting (clang-format), static analysis (cppcheck), and run the full build-and-test cycle:

pip install pre-commit
pre-commit install

You can also run the format checker directly:

scripts/check-format.sh       # check only
scripts/check-format.sh fix   # auto-format in place

Releasing

1. Update the version in configure.ac (AC_INIT(pngtools, [X.Y]))
2. Commit and push to master
3. Go to Actions > Release > Run workflow
4. Enter the version string (must match configure.ac)

The workflow will:

• Verify the version matches configure.ac
• Build and run the full test suite
• Create a make dist tarball (includes test suite and test images)
• Create a Sigstore-signed git tag (vX.Y)
• Publish a GitHub Release with the tarball and changelog
• Attest the tarball provenance via Sigstore

Release artifacts can be verified with:

gh attestation verify pngtools-X.Y.tar.gz --owner mikalstill

Documentation

• ARCHITECTURE.md -- code structure, data flow, and known bugs
• AGENTS.md -- guidelines for AI agents working on this codebase
• Man pages are built from DocBook SGML sources in the man/ directory

License

GNU General Public License v2. See COPYING for details.

Author

Michael Still (mikal@stillhq.com) https://www.madebymikal.com/category/pngtools/