Repository navigation
archive support
github-actions[bot] edited this page Oct 4, 2026
·
3 revisions
Detected by file extension (ArchiveFormats):
| Extension | Format |
|---|---|
.zip |
ZIP |
.7z |
7-Zip |
.rar |
RAR |
.tar |
TAR |
.tar.gz, .tgz
|
GZIP-compressed TAR |
.tar.bz2, .tbz2
|
BZIP2-compressed TAR |
.tar.xz, .txz
|
XZ-compressed TAR |
.cbz, .cbr, .cb7
|
Comic-book archives (ZIP/RAR/7Z containers) |
.zar |
ZArchive — Zstd seekable container with per-block random access |
.iso, .xiso
|
Xbox XISO disc images (XDVDFS filesystem, all disc layouts: RAW, GLOBAL/XGD2, XGD3, Hybrid, XGD1) |
.cso |
Compressed Xbox disc images (CISO, including split .1.cso part sets) |
Everything else is rejected with "The file 'X' is not a supported archive" and the list of expected extensions. The mount is read-only — archives are never modified.
Xbox images: the
.isosupport targets the Xbox XDVDFS format only — generic ISO 9660/UDF images are rejected at mount time with "The file is not a valid Xbox XISO disc image". Files are read on demand straight from the image sectors (no extraction);.csodata is decompressed block-by-block through XISOSharp.
| Situation | Path |
|---|---|
| ZIP stored entry (no compression, not encrypted/solid) | Zero-copy direct read — no decompression, no cache (details) |
.zar, Xbox .iso / .cso entry |
Read on demand through ZArchiveSharp/XISOSharp (touched Zstd/CISO blocks decoded per read), then cached by the size tiers below |
| Compressed entry ≤ per-file RAM limit (512 MB default) | Decompress once into the shared memory cache |
| Compressed entry above the limit | Extract once to the disk cache |
| SharpCompress fails to decompress | 7-Zip fallback (below) |
- Encryption is detected by entry flags plus a test read of up to 1 KB per encrypted entry (some ZIP tools set the encryption flag incorrectly, so the app verifies instead of trusting the flag).
- A verified-encrypted archive shows the Password Required dialog before mounting.
- The password is verified by reading 1 KB from every encrypted entry — a wrong password is caught at mount time, not mid-file.
- 3 attempts maximum, then "Mount aborted after 3 attempts." Cancelling the dialog cancels the mount.
- Corrupt archives are deliberately not treated as password problems: a truncated/corrupt RAR surfaces as a corruption error instead of looping the password dialog (fixed in 2.9.0).
- The password is kept only for the duration of the mount session and cleared after use.
- Unparseable archives: "The archive file appears to be corrupted, incomplete, or uses an unsupported format/feature that could not be parsed."
- Corruption found while enumerating entries: "Archive data corruption detected during initialization." — mounting aborts.
- Individual entries that fail to decompress are marked failed and return read errors instead of poisoning the whole mount; the log names the entry and the failure.
When SharpCompress (the primary extraction library) fails to decompress an entry, SimpleZipDrive retries with the 7-Zip engine by running the bundled command-line executable:
- The platform binary ships beside the executable and is selected by
RuntimeIdentifier:7za.exeon Windows, statically linked7zzson Linux, universal7zzon macOS. No native library is loaded into the process, so architecture mismatches cannot occur; on Unix the app sets the executable bit at startup if the archive tool dropped it. - Only available when the archive is a real file (not a pipe) so the extractor can open it by path.
- The extractor runs headless (
-bd -y), with standard input closed so a missing password can never hang a prompt, exact-name matching (-spd), and stdout streaming (-so) straight into the cache — the entry is never written to an intermediate folder. - Entry names are mapped through
7z l -slt, so names stored with backslashes or wildcard characters ([,]) are extracted correctly. - The fallback receives the same password (if any) as the primary path.
- If the fallback also fails: "SevenZip fallback also failed for '…'" and the entry is marked failed.
- The bundled
7za.exesupports 7z, xz, lzma, cab, zip, gzip, bzip2, Z, and tar but not RAR; Linux/macOS use the full7zzbuild, which can also read RAR. RAR archives normally extract through SharpCompress, so this only matters for an entry SharpCompress failed on.
Packaging note: the 7-Zip binary must stay next to the executable. The exact file name and the
7zip-license.txtnotice are documented in Building & Packaging.
- ZIP64 archives (over 4 GB / 65 535 entries) are handled by SharpCompress.
- Solid archives (common in 7Z/RAR) cannot use the zero-copy path; reads decompress through the cache tiers, so first-access cost is higher.
- Multi-volume/split ZIP/7Z/RAR archives are not supported; split CISO Xbox images (
.1.cso,.2.cso, …) are. -
.zarcontainers are created by ZArchiveSharp-compatible tooling (the Xbox 360 scene's archival format);.csoimages are created by CISO packers such as xdvdfs/XISOSharp. - For best performance with large game images, prefer a format with native random access: uncompressed ZIP,
.zar(Zstd seekable), or a plain Xbox.iso(see Performance).
Resources