pngcheck: Quick Guide to Verifying PNG Files

How to Use pngcheck to Inspect PNG Metadata and Integritypngcheck is a small, focused command-line utility for validating PNG (Portable Network Graphics) files and inspecting their structure and metadata. It verifies file integrity, reports on chunk contents (including ancillary chunks such as tEXt, iTXt, zTXt, gAMA, sRGB, pHYs), and can reveal corrupted or malformed files that other tools might silently accept. This article explains installation, basic and advanced usage, interpreting output, common troubleshooting, and practical scripting examples.

---

Why use pngcheck?

• Lightweight and fast: Runs from the command line with no heavy dependencies.
• PNG-aware: Understands the PNG chunk structure and flags format errors and CRC mismatches.
• Metadata inspection: Shows textual and other ancillary chunks that carry metadata (author, software, color information, etc.).
• Diagnostic tool: Helpful to developers, image pipeline maintainers, and archivists verifying large collections.

---

Installation

pngcheck is available on major platforms.

• macOS: brew install pngcheck
• Debian/Ubuntu: sudo apt-get install pngcheck or sudo apt install pngcheck
• Fedora: sudo dnf install pngcheck
• Windows: Download precompiled binaries from the pngcheck website and add to PATH, or use package managers like Chocolatey (choco install pngcheck) if available.
• From source: download the source tarball from the official site and compile with a C compiler (make).

---

PNG basics (brief)

PNG files are a sequence of chunks. Each chunk has:

• 4-byte length
• 4-byte chunk type (ASCII, case-significant)
• data bytes
• 4-byte CRC

Critical chunks include IHDR, IDAT, and IEND. Ancillary chunks include tEXt/iTXt (text metadata), zTXt (compressed text), gAMA (gamma), sRGB (rendering intent), pHYs (pixel dimensions), and others. pngcheck reads and validates these structures.

---

Basic usage

Run pngcheck on a file to validate the structure and show chunk listing:

pngcheck file.png 

Typical concise output lists chunks with their offsets, lengths, and types, for example:

• 00000000: PNG (signature)
• 00000008: IHDR 13
• 00000021: sRGB 1
• 0000002A: gAMA 4
• 00000032: IDAT 8192
• 00002032: IEND 0

If the file is valid you’ll see no CRC or format errors; if there are problems, pngcheck reports them.

---

Useful command-line options

• -v or -vv — verbose output. -vv is very verbose and prints chunk contents where appropriate.
• -s — show file size (in bytes) with output.
• -c — check CRCs (this is done by default for PNG files; used with some other formats).
• -t — show textual chunk contents (tEXt, iTXt, zTXt). Combine with -v for more detail.
• -g — show gamma information (gAMA) in human-readable form.
• -m — report basic metadata (IHDR fields like width, height, bit depth, color type, compression, filter, interlace).
• -q — quiet; minimal output.
• -f — force checking files that do not have a .png extension.
• -I — show image information only (summary of IHDR and color info).
• -k — keep going after encountering errors (useful when scanning many files).
• --raw-chunks — display raw chunk data (use with care; can be large).
• -h — display help.

Combine options, for example:

pngcheck -v -t image.png 

This prints verbose chunk listing and textual metadata.

---

Interpreting common output

• IHDR line shows width, height, bit depth, color type, compression, filter, interlace. Example: IHDR 1024 x 768, 8-bit RGBA, non-interlaced
• IDAT chunks: indicated with their sizes; many files have multiple IDAT chunks.
• sRGB/gAMA: color rendering and gamma information used by viewers; incorrect values can cause color shifts.
• tEXt/iTXt/zTXt: textual metadata entries; -t or -vv shows their key/value pairs.
• pHYs: pixel density (units per meter). Useful for print/DPI mapping.
• CRC errors: pngcheck reports CRC mismatches like “CRC error in chunk IDAT” — indicates corruption or tampering.
• Unrecognized chunks: shown as unknown chunk types; ancillary chunks have lowercase letters in certain positions indicating their safety to copy.

---

Examples

1. Quick integrity check of one file:

pngcheck -s file.png 

1. Show all textual metadata and verbose chunk contents:

pngcheck -vv -t file.png 

1. Check many files in a directory, continue on error, and show only problematic files:

for f in *.png; do pngcheck -k "$f" > /dev/null || echo "Bad: $f"; done 

(Replace with a platform-appropriate loop on Windows PowerShell.)

1. Inspect a PNG stream inside a larger file (force check):

pngcheck -f embedded-data.bin 

1. Save textual metadata to a file:

pngcheck -t image.png > image-metadata.txt 

---

Scripting and bulk validation

When validating large image collections, incorporate pngcheck into pipelines:

• Parallel checks with GNU parallel:

ls *.png | parallel -j8 'pngcheck -q {} || echo {} >> bad-files.txt' 

• In Python, call pngcheck via subprocess and parse output for IHDR and CRC errors; or use pngcheck’s -m and -t flags to restrict output for easier parsing.

• Use -k to keep scanning despite errors and aggregate results.

---

Troubleshooting problems pngcheck finds

• CRC errors: try re-downloading or restoring from backup. If only metadata chunks show CRC issues, consider re-saving the image with an editor that preserves image data (e.g., pngcrush, ImageMagick convert).
• Incorrect gAMA/sRGB: re-assign correct profile using tools like ImageMagick (e.g., convert file.png -strip -gamma 1.0 out.png) or embed a proper ICC profile with dedicated tools.
• Broken IDAT or truncated file: usually unrecoverable unless a previous copy exists; sometimes partial recovery by extracting IDAT streams is possible but complex.
• Unexpected ancillary chunks: often harmless, but review keys/values if they contain sensitive metadata (author, software, timestamps).

---

Comparing pngcheck to other tools

Tool	Strengths	Weaknesses
pngcheck	Fast, chunk-level validation, shows metadata	Command-line only, limited repair capabilities
pngcrush	Can optimize and rewrite PNGs, fix some issues	Focused on optimization; more invasive
ImageMagick (identify/convert)	Versatile image processing, format conversion	May accept corrupted files silently; less chunk detail
pngfix (part of libpng-tools)	Attempts simple repairs	Less informative reporting than pngcheck

---

Advanced tips

• Use pngcheck -vv only when you need detailed chunk contents, as it can produce large output and expose binary content.
• When scripting, parse only the specific lines you need (IHDR, CRC errors) rather than entire verbose dumps.
• Combine pngcheck with tools like exiftool to reveal other embedded metadata formats that pngcheck doesn’t show (EXIF in PNG is rare but possible via iTXt).
• For forensic verification, compare computed CRCs and chunk ordering against known-good files.

---

Security and privacy notes

pngcheck inspects file contents locally; using it on untrusted PNGs is generally safe, but follow best practices: run on isolated environments when analyzing potentially malicious files and avoid executing any binary content extracted from chunks.

---

Summary

pngcheck is a focused, reliable tool for validating PNG structure and inspecting metadata. Use it to detect CRC errors, list chunks and textual metadata, and integrate it into batch-checking pipelines to maintain image-collection health.