Inspect a ZIP archive's internal structure with zipdetails

You will produce a readable, offset-by-offset report of a ZIP archive, then choose the right level of detail for troubleshooting. The installed zipdetails is Perl 5.38.2's version 2.104. Allow about ten minutes for a small archive, plus time to interpret the ZIP format if the problem is unusual.

This is an inspection tool. It does not extract files, repair an archive or change the input. You normally run it as your ordinary user, with no sudo.

1. Check the installed command

Confirm which executable will run and record its version. This matters when you are comparing reports from different hosts or pasting output into a bug report.

$ command -v zipdetails
/usr/bin/zipdetails
$ zipdetails --version
2.104

The version number and path can differ on another Linux system. If the command is missing, install the package that provides it through your normal package-management process. Do not download a replacement script into a shared path just to investigate one archive.

2. Read a normal structural report

Pass the archive as the only positional argument:

$ zipdetails /path/to/archive.zip

The default report has three useful columns. The first is the hexadecimal offset from the beginning of the file. The second names the ZIP field. The third shows a decoded value, often in hexadecimal, followed by a human-readable interpretation where one is available.

A small archive will contain local headers near the start, file payloads, central-directory headers later, and an end-central-header record at the end. A successful report ends with:

Done

Do not treat Done as proof that every byte is semantically correct. The program's structural checks are useful but incomplete, and malformed data can terminate it with an unhelpful error.

The dates shown by default are in the machine's local time. If two people are comparing output from different time zones, they can appear to disagree about the archive even when the stored DOS timestamp is the same.

3. Add byte-level detail when an offset matters

Use -v when you need to correlate a field with the bytes stored on disk:

$ zipdetails -v /path/to/archive.zip | sed -n '1,20p'

0000 0004 50 4B 03 04 LOCAL HEADER #1       04034B50
0004 0001 0A          Extract Zip Spec      0A '1.0'
0005 0001 00          Extract OS            00 'MS-DOS'

Verbose mode expands the first column to include the offset, field length and a hex dump in the order the bytes occur in the ZIP file. The report remains a report, not a hexdump of every byte: it groups bytes according to the fields that zipdetails recognises.

Use this mode when a central-directory offset, length, CRC or header signature needs checking. Keep the unfiltered output when sharing evidence, because the surrounding records provide context.

4. Make timestamps comparable

Use --utc to display date and time fields in Coordinated Universal Time:

$ zipdetails --utc /path/to/archive.zip | grep 'Last Mod Time'
000A Last Mod Time         5D3C7D7D 'Mon Sep 28 15:43:58 2026'
0053 Last Mod Time         5D3C7D7D 'Mon Sep 28 15:43:58 2026'

The offsets, hexadecimal value and number of matching records depend on the archive. The useful verification is that the command completed and the displayed time is explicitly UTC for your comparison. ZIP timestamps have their own format and precision limits, so UTC output does not create precision that was not stored.

5. Redact filenames before sharing output

Filenames can disclose customer names, internal paths or other sensitive information. Use --redact when the structure matters but names do not:

$ zipdetails --redact /path/to/archive.zip | grep -E 'Filename|Done'
001E Filename              'XXXXXXXXX'
0067 Filename              'XXXXXXXX'
Done

The replacement length reflects the original filename length. Redaction only obscures filenames in the report. It does not encrypt the archive, remove names from the input, or conceal other metadata and payload bytes. Treat verbose output as sensitive unless you have checked it first.

6. Try scan mode for a damaged archive

Normal mode expects a well-formed ZIP and starts by parsing the central directory at the end. If that directory is absent or incomplete, try --scan:

$ zipdetails --scan /path/to/possibly-damaged.zip

Scan mode walks from the start and looks blindly for recognised four-byte ZIP signatures. It may recover records that are still present when the central directory cannot be read. It can also mistake random payload bytes for a ZIP signature, so every apparent header needs corroboration from its offset, lengths and surrounding records.

Scanning a very large file can take a long time. Do not mistake a long-running scan for a hung process, and do not run it against a path that is still being written. Make a stable copy first if another process is producing the archive:

$ cp --reflink=auto -- /path/to/archive.zip /tmp/archive-for-inspection.zip
$ zipdetails --scan /tmp/archive-for-inspection.zip

The copy is an additional file and can consume disk space. Remove it after the investigation with an explicit path once you have finished reviewing it.

7. Handle failures without changing the evidence

If zipdetails cannot open the file, check the path and read permission without modifying anything:

$ ls -l -- /path/to/archive.zip
$ test -r /path/to/archive.zip && echo readable

A non-zero result from test means the current user cannot read the file. Ask the file owner or administrator for access rather than changing permissions on a shared archive. Elevated privileges are not a repair method.

If normal mode stops early or reports structural trouble, preserve the original and retry with --scan. Compare the output with another independent tool, such as zipinfo, before deciding that a recovered record is genuine. Neither mode repairs the archive. Work on a copy if a later repair tool is required, and keep the original unchanged as your evidence.

The installed program does not support multi-part archives or the strong encryption features defined by the ZIP specification. An encrypted or split archive can therefore be outside what this report can explain. Do not publish a verbose report from a confidential archive without reviewing filenames, comments, extra fields and payload previews first.