MOUNT-ZIP(1)

📦 version 1.16, in nixos 26.05, nixpkgs unstable

💖 NAME 💖

Okay so the MOUNT-ZIP(1) manual page is for mount-zip, and its whole slay is: Mount ZIP archives as FUSE file systems. Periodt.

✨ SYNOPSIS ✨

mount-zip [options] zip-file
mount-zip [options] zip-file mount-point
mount-zip [options] zip-file-1 zip-file-2 ... mount-point

🌸 DESCRIPTION 🌸

mount-zip mounts one or several ZIP archives as a read-only FUSE file system. It starts fast, uses little memory, decodes encrypted files, and gives you on-the-go decompression and caching for maximum efficiency. Iconic.

It automatically creates the target mount point if needed. If no mount point is specified, mount-zip creates a mount point in the current working directory. Cute, right?

💅 OPTIONS 💅

--help or -h — prints help.
--version or -V — prints program version.
-o quiet or -q — prints fewer log messages.
-o verbose or -v — prints more detailed log messages.
-o redact — redacts file names from log messages.
-o force — continues even if the given password is wrong or missing, or if the encryption or compression method is unsupported. This is the continue-anyway option, bestie.
-o precache — preemptively decompresses and caches the whole ZIP archive(s).
-o cache=DIR — uses a different cache directory (default is $TMPDIR or /tmp).
-o memcache — caches the decompressed data in memory.
-o nocache — does not cache the decompressed data.
-o encoding=CHARSET — original encoding of file names.
-o nomerge — does not merge multiple ZIP archives on top of each other. Instead, it creates a subdirectory for each ZIP archive inside the mount point.
-o notrim — does not trim the base of the tree. Keeps all the intermediate directories as specified in the ZIP archive(s).
-o nodirs — no directories. Flattens the archive structure by presenting all its files in its root directory. This might make sense if you’re not interested in the archive tree structure, but only in its file data, e.g. for malware scanning.
-o nospecials — hides special files (FIFOs, sockets, devices).
-o nosymlinks — hides symbolic links.
-o nohardlinks — hides hard links.
-o dmask=M — directory permission mask in octal (default 0022).
-o fmask=M — file permission mask in octal (default 0022).
-o uid=N — sets the user ID of all the items in the mounted archive (default is current user).
-o gid=N — sets the group ID of all the items in the mounted archive (default is current group).
-o enforce_permissions — uses the user ID, group ID and permissions stored with each item in the archive.
-f — foreground mode.
-d — foreground mode with debug output.

🦋 USAGE EXAMPLES 🦋

Mount a ZIP archive:

$ mount-zip foobar.zip mnt

The mounted ZIP archive can be explored and read using any application:

$ tree mnt
mnt
└── foo

0 directories, 1 file

$ cat mnt/foo
bar

When finished, unmount the file system:

$ umount mnt

🔥 FEATURES 🔥

Read-only view
Instant mounting, even with big ZIP archives
Compression methods: deflate, bzip2
Encryption methods: AES and legacy ZIP encryption
Asks for decryption password if necessary
Detects file name encoding
Converts file names to Unicode UTF-8
Deduplicates files in case of name collisions
Unpacks files when reading them (on-the-go decompression)
Supports all file types, including named sockets, FIFOs, block and character devices, symbolic links and hard links
Supports Unix access modes and DOS file permissions
Supports owner and group information (UID and GID)
Supports relative and absolute paths
Supports high-precision timestamps
Works on 32-bit and 64-bit devices
Supports ZIP64 extensions, even on 32-bit devices:
- Supports ZIP archives containing more than 65,535 files
- Supports ZIP archives and files bigger than 4 GB
Supports the following ZIP format extensions:
- 000A PKWARE NTFS high-precision timestamps
- 000D PKWARE Unix file type
- 5455 Unix timestamps
- 5855 Info-ZIP Unix extra fields (type 1)
- 7855 Info-ZIP Unix extra fields (type 2)
- 7875 Info-ZIP Unix extra fields (type 3): UID and GID

🧚 FILE NAME ENCODING 🧚

mount-zip is fully Unicode compliant. It converts the file names stored in the ZIP archive from their original encoding to UTF-8.

In order to interpret these file names correctly, mount-zip needs to determine their original encoding. By default, mount-zip tries to guess this encoding using the detection feature provided by the ICU library. It can automatically recognize the following encodings:

UTF-8
CP437
Shift JIS
Big5
EUC-JP
EUC-KR
GB18030
ISO-2022-CN
ISO-2022-JP
ISO-2022-KR
KOI8-R

For example, when mounting a ZIP containing a Shift JIS-encoded file name, the encoding is correctly detected:

$ mount-zip sjis-filename.zip mnt

$ tree mnt
mnt
└── 新しいテキスト ドキュメント.txt

0 directories, 1 file

This system is not foolproof, and doesn’t recognize a number of popular encodings. For example, when mounting a ZIP containing file names encoded in CP866, they are interpreted as CP437 and rendered as Mojibake:

$ mount-zip cp866.zip mnt

$ tree mnt
mnt
├── äáΓá
└── ÆÑ¬ßΓ«óδ⌐ ñ«¬π¼Ñ¡Γ.txt

0 directories, 2 files

In this case, the user needs to explicitly specify the original file name encoding using the -o encoding mount option:

$ mount-zip -o encoding=cp866 cp866.zip mnt

$ tree mnt
mnt
├── Дата
└── Текстовый документ.txt

0 directories, 2 files

💜 NAME DEDUPLICATION 💜

In case of name collision, mount-zip adds a number to deduplicate the conflicting file name:

$ unzip -l file-dir-same-name.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
       25  2021-10-29 14:22   pet/cat
       21  2021-10-29 14:22   pet
       30  2021-10-29 14:22   pet/cat/fish
        0  2021-10-29 14:22   pet/cat/fish/
       26  2021-10-29 14:22   pet/cat
       22  2021-10-29 14:22   pet
       31  2021-10-29 14:22   pet/cat/fish
---------                     -------
      155                     7 files

$ mount-zip file-dir-same-name.zip mnt

$ tree -F mnt
mnt
├── pet/
│   ├── cat/
│   │   ├── fish/
│   │   ├── fish (1)
│   │   └── fish (2)
│   ├── cat (1)
│   └── cat (2)
├── pet (1)
└── pet (2)

3 directories, 6 files

Directories are never renamed. If a file is colliding with a directory, the file will be the one getting renamed. 💅

🔐 ENCRYPTED ARCHIVES 🔐

okay so bestie, mount-zip is NOT scared of encrypted ZIPs 💪 it understands the legacy ZIP encryption scheme, plus the more recent AES encryption schemes (AES-128, AES-192 and AES-256). all three, yes ma'am.

When mount-zip finds an encrypted file while mounting a ZIP archive, it asks for a password. and like… if the given password does not decrypt the file, then mount-zip refuses to mount the ZIP archive and returns an error. no half-mounting, no vibes-based access, just straight up:

$ unzip -l different-encryptions.zip
Archive:  different-encryptions.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
       23  2020-08-28 15:22   ClearText.txt
       32  2020-08-28 15:23   Encrypted AES-128.txt
       32  2020-08-28 15:23   Encrypted AES-192.txt
       32  2020-08-28 15:23   Encrypted AES-256.txt
       34  2020-08-28 15:23   Encrypted ZipCrypto.txt
---------                     -------
      153                     5 files

$ mount-zip different-encryptions.zip mnt
Need password for File [1] '/Encrypted AES-128.txt'
Password > Got it!
Use the -o force option to mount an encrypted ZIP with a wrong password
Cannot open File [1] '/Encrypted AES-128.txt': Wrong password provided

Providing the correct password allows mount-zip to mount the ZIP archive and decode the files 💖 look at her go:

$ mount-zip different-encryptions.zip mnt
Need password for File [1] '/Encrypted AES-128.txt'
Password > Got it!
Password is Ok

$ tree mnt
mnt
├── ClearText.txt
├── Encrypted AES-128.txt
├── Encrypted AES-192.txt
├── Encrypted AES-256.txt
└── Encrypted ZipCrypto.txt

0 directories, 5 files

$ md5sum mnt/*
7a542815e2c51837b3d8a8b2ebf36490  mnt/ClearText.txt
07c4edd2a55c9d5614457a21fb40aa56  mnt/Encrypted AES-128.txt
e48d57930ef96ff2ad45867202d3250d  mnt/Encrypted AES-192.txt
ca5e064a0835d186f2f6326f88a7078f  mnt/Encrypted AES-256.txt
275e8c5aed7e7ce2f32dd1e5e9ee4a5b  mnt/Encrypted ZipCrypto.txt

$ cat mnt/*
This is not encrypted.
This is encrypted with AES-128.
This is encrypted with AES-192.
This is encrypted with AES-256.
This is encrypted with ZipCrypto.

You can force mount-zip to mount an encrypted ZIP even without providing the right password by using the -o force option:

$ mount-zip -o force different-encryptions.zip mnt
Need password for File [1] '/Encrypted AES-128.txt'
Password > Got it!
Continuing despite wrong password because of -o force option

In this case, the files can be listed, but trying to open an encrypted file for which the given password doesn't work results in an I/O error 😭 and that's the whole era:

$ tree mnt
mnt
├── ClearText.txt
├── Encrypted AES-128.txt
├── Encrypted AES-192.txt
├── Encrypted AES-256.txt
└── Encrypted ZipCrypto.txt

0 directories, 5 files

$ md5sum mnt/*
7a542815e2c51837b3d8a8b2ebf36490  mnt/ClearText.txt
md5sum: 'mnt/Encrypted AES-128.txt': Input/Output error
md5sum: 'mnt/Encrypted AES-192.txt': Input/Output error
md5sum: 'mnt/Encrypted AES-256.txt': Input/Output error
md5sum: 'mnt/Encrypted ZipCrypto.txt': Input/Output error

$ cat mnt/*
This is not encrypted.
cat: 'mnt/Encrypted AES-128.txt': Input/Output error
cat: 'mnt/Encrypted AES-192.txt': Input/Output error
cat: 'mnt/Encrypted AES-256.txt': Input/Output error
cat: 'mnt/Encrypted ZipCrypto.txt': Input/Output error

🔒 For security reasons, mount-zip doesn't allow the password to be specified on the command line. no secrets in your shell history, babes. However, it is possible to pipe the password to mount-zip's standard input:

$ echo password | mount-zip different-encryptions.zip mnt
Need password for File [1] '/Encrypted AES-128.txt'
Password is Ok

🦋 FILE TYPES 🦋

🎀 Symbolic links 🎀

mount-zip shows symbolic links recorded in the ZIP archive:

$ mount-zip symlink.zip mnt

$ tree mnt
mnt
├── date
└── symlink -> ../tmp/date

⚠️ Note that symbolic links can refer to files located outside the mounted ZIP archive. In some circumstances, these links could pose a security risk. bestie please read that twice, k?

Symbolic links can be suppressed with the -o nosymlinks option:

$ mount-zip -o nosymlinks symlink.zip mnt
Skipped Symlink [1] '/symlink'

2021-10-28 20:05:01 laptop ~/mount-zip/tests/blackbox/data (intrusive)
$ tree mnt
mnt
└── date

0 directories, 1 file

👑 Special Files 👑

mount-zip shows special files (sockets, FIFOs or pipes, character and block devices) recorded in the ZIP archive:

$ mount-zip -o enforce_permissions pkware-specials.zip mnt

$ ls -n mnt
brw-rw---- 1    0    6 8, 1 Aug  3  2019 block
crw--w---- 1    0    5 4, 0 Aug  3  2019 char
prw-r--r-- 1 1000 1000    0 Aug 15  2019 fifo
-rw-r--r-- 3 1000 1000   32 Aug  9  2019 regular
srw------- 1 1000 1000    0 Aug  3  2019 socket
lrwxrwxrwx 1 1000 1000    7 Aug  3  2019 symlink -> regular
lrwxrwxrwx 1 1000 1000    7 Aug 25  2019 symlink2 -> regular
-rw-r--r-- 3 1000 1000   32 Aug  9  2019 z-hardlink1
-rw-r--r-- 3 1000 1000   32 Aug  9  2019 z-hardlink2
brw-rw---- 1    0    6 8, 1 Aug  3  2019 z-hardlink-block
crw--w---- 1    0    5 4, 0 Aug  3  2019 z-hardlink-char
prw-r--r-- 1 1000 1000    0 Aug 15  2019 z-hardlink-fifo
srw------- 1 1000 1000    0 Aug  3  2019 z-hardlink-socket
lrwxrwxrwx 1 1000 1000    7 Aug  3  2019 z-hardlink-symlink -> regular

Special files can be suppressed with the -o nospecials option. 🫶

💜 Hard Links 💜

mount-zip shows hard links recorded in the ZIP archive.

In this example, the three file entries 0regular, hlink1 and hlink2 point to the same inode number (2) and their reference count is 3:

$ mount-zip hlink-chain.zip mnt

$ ls -ni mnt
2 -rw-r--r-- 3 0 0 10 Aug 14  2019 0regular
2 -rw-r--r-- 3 0 0 10 Aug 14  2019 hlink1
2 -rw-r--r-- 3 0 0 10 Aug 14  2019 hlink2

$ md5sum mnt/*
e09c80c42fda55f9d992e59ca6b3307d  mnt/0regular
e09c80c42fda55f9d992e59ca6b3307d  mnt/hlink1
e09c80c42fda55f9d992e59ca6b3307d  mnt/hlink2

Some tools can use the inode number to detect duplicated hard links. In this example, du only counts the size of the inode (2) once, even though there are three file entries pointing to it, and only reports 10 bytes instead of 30 bytes. she's efficient, she's iconic:

$ du -b mnt
10      mnt

Duplicated hard links can be suppressed with the -o nohardlinks option.

✨ CACHING ✨

mount-zip only does the minimum amount of work required to serve the requested data. It offers several caching strategies and storage options to balance performance, mount time, and resource usage. lowkey a whole personality trait ngl.

🌸 Caching Strategies 🌸

The following strategies are mutually exclusive. If none is specified, lazy decompression is used by default. pick one, bestie, you can't have all three 💅

Lazy Decompression (Default)

By default, mount-zip only decompresses enough data to serve the reading application. Accessing the beginning of a big compressed file is therefore instantaneous. mount-zip will start caching a file if it detects that this file is getting read in a non-sequential way. main character energy: does exactly what's needed, nothing extra 💖

Pre-emptive Caching (`-o precache`)

The -o precache option instructs mount-zip to preemptively decompress and cache the whole ZIP archive(s) at mount time. The cost of decompression is incurred upfront, ensuring that any subsequent access to the served data is fast and supports efficient random access 🔥

No Caching (`-o nocache`)

The -o nocache option disables long-term caching. mount-zip will use a small rolling buffer in memory to serve data. This minimizes disk and memory usage but can be significantly slower for non-sequential access patterns or if the same files are read repeatedly, as data may need to be re-decompressed. 😭 yes it's tiny, no it's not fast, tradeoffs are real.

🎀 Storage Options 🎀

Disk Caching (Default)

By default, decompressed data is cached in an anonymous temporary file (in $TMPDIR or /tmp). This cache can use a significant amount of disk space but is automatically deleted when the ZIP is unmounted. The cache directory can be changed with the -o cache=DIR option. it cleans up after itself, we love a self-aware queen ✨

Memory Caching (`-o memcache`)

The -o memcache option instructs mount-zip to store the cache in RAM instead of a temporary file. This provides the highest performance but can consume a large amount of memory. It can be used with both lazy and pre-emptive caching strategies. 🧚 fast as heck, hungry as heck.

🔥 ADVANCED OPTIONS 🔥

💀 Handling Errors (`-o force`) 💀

The -o force option allows mount-zip to continue mounting a ZIP archive even if some errors are encountered. This includes:

Wrong or missing decryption passwords.
Unsupported compression or encryption methods.

In these cases, files that cannot be correctly processed will still be listed in the directory tree, but attempting to read them will result in an Input/Output error (EIO). so like… they're there, they're just not giving. 🙈

🫶 Permissions and Ownership 🫶

By default, mount-zip presents all files as being owned by the current user and group, with standard read permissions. simple, clean, no drama.

User and Group IDs (`-o uid=N`, `-o gid=N`)

You can explicitly set the user and group of all items in the mounted archive using the -o uid and -o gid options with the desired numerical IDs. numbers only, she's specific like that.

Using Archive Permissions (`-o enforce_permissions`)

The -o enforce_permissions option instructs mount-zip to use the exact UID, GID, and Unix permission bits stored within the archive for each item. This includes support for special bits such as SUID, SGID, and SVTX (sticky bit). 👑

⚠️ Note that this may result in access denied errors if you are not the owner of the files inside the archive. respectfully, the archive said what it said.

Permission Masks (`-o dmask=M`, `-o fmask=M`)

You can apply an octal permission mask to directories (dmask) and files (fmask). For example, -o fmask=077 would remove all permissions for group and others from files. mask on, mask off, your call bestie 💅

🔥 PERFORMANCE 🔥

Okay so this is the part where mount-zip flexes, and honestly? It slays. It handles huge archives with so many files, no cap. On the author's laptop, a ZIP with more than 70,000 files gets mounted in half a second — literally blink and it's done:

$ ls -lh linux-5.14.15.zip
-rw-r--r-- 1 fdegros primarygroup 231M Oct 28 15:48 linux-5.14.15.zip

$ time mount-zip linux-5.14.15.zip mnt

real    0m0.561s
user    0m0.344s
sys     0m0.212s

$ tree mnt
mnt
└── linux-5.14.15
    ├── arch
...

4817 directories, 72539 files

$ du -sh mnt
1.1G    mnt

The whole mounted ZIP is 1.1 GB, and you can pull all of it out with cp -R in 14 seconds:

$ time cp -R mnt out

real    0m13.810s
user    0m0.605s
sys     0m5.356s

For comparison? unzip does the same ZIP in 8.5 seconds:

$ time unzip -q -d out linux-5.14.15.zip

real    0m8.411s
user    0m6.067s
sys     0m2.270s

And mounting an 8-GB ZIP with only a few files in it is basically instantaneous 🫶:

$ ls -lh bru.zip
-rw-r----- 1 fdegros primarygroup 7.9G Sep  2 22:37 bru.zip

$ time mount-zip bru.zip mnt

real    0m0.033s
user    0m0.018s
sys     0m0.011s

$ tree -h mnt
mnt
├── [2.0M]  bios
├── [ 25G]  disk
└── [ 64M]  tools

0 directories, 3 files

Decompressing and reading that 25-GB file from the mounted ZIP? Less than two minutes, bestie:

$ dd if=mnt/disk of=/dev/null status=progress
26843545600 bytes (27 GB, 25 GiB) copied, 104.586 s, 257 MB/s

No lag when opening and reading the file, and only a moderate amount of memory gets used 💅. The file is getting lazily decompressed by mount-zip as it's getting read by the dd program. Iconic behaviour.

📝 LOG MESSAGES 📝

mount-zip records log messages to the system logger (syslog). These messages are your besties when you're troubleshooting stuff — like I/O errors, or archives that straight up refuse to mount 😭.

To read mount-zip's log messages on most Linux systems:

$ journalctl -t mount-zip

Alternatively, you can run mount-zip in the foreground with the -f option and see log messages directly on your terminal. Very main character of you.

By default, mount-zip writes INFO and ERROR messages. You can decrease the logging level to just ERROR messages with the -o quiet option, or increase it to include DEBUG messages with the -o verbose option:

$ mount-zip -f -o verbose foobar.zip mnt
Indexing 'foobar.zip'...
Allocating 16 buckets
Detected encoding UTF-8 with 15% confidence
Indexed 'foobar.zip' in 0 ms
Mounted 'foobar.zip' on 'mnt' in 2 ms
Reader 1: Opened File [0]
Reader 1: Closed
Unmounting 'foobar.zip' from 'mnt'...
Unmounted 'foobar.zip' in 0 ms

If you don't want file names showing up in mount-zip's log messages, use the -o redact option:

$ mount-zip -f -o verbose -o redact bad-crc.zip mnt
Indexing (redacted)...
Allocating 16 buckets
Indexed (redacted) in 0 ms
Mounted (redacted) on (redacted) in 2 ms
Reader 1: Opened File [0]
Cannot read (redacted): Cannot read file: CRC error
Reader 1: Closed
Unmounting (redacted) from (redacted)...
Unmounted (redacted) in 0 ms

🚦 RETURN VALUE 🚦

mount-zip returns distinct error codes for different error conditions related to the ZIP archives themselves. Not me being obsessed with precise exit codes... okay maybe a little 🙈

0 — Success. We love to see it ✨
1 — Generic error code for: missing argument, unknown option, unknown file name encoding, mount point cannot be created, mount point is not empty, etc.
11 — An archive is a multipart ZIP.
15 — A ZIP archive cannot be read.
19 — A ZIP archive cannot be found.
21 — A ZIP archive cannot be opened.
23 — Decompression error. This is probably the sign of a wrong password. Use -o force to bypass the password verification.
26 — Unsupported compression method. Use -o force to bypass the compression method verification.
29 — An archive is not recognized as a valid ZIP.
31 — A ZIP archive has an inconsistent structure.
34 — Unsupported encryption method. Use -o force to bypass the encryption method verification.
36 — Password needed. A ZIP archive contains an encrypted file, but no password was provided. Use -o force to bypass the password verification.
37 — Wrong password. A ZIP archive contains an encrypted file, and the provided password does not decrypt it. Use -o force to bypass the password verification.
45 — Possibly truncated or corrupted ZIP archive, as detected by libzip 1.11 or higher.

Ngl bestie, most of these have a -o force escape hatch, but force means you're overriding a real verification check. You've been warned 💀

🧚 PROJECT HISTORY 🧚

mount-zip started as a fork of fuse-zip. A whole origin story, honestly.

The original fuse-zip project was created in 2008 by Alexander Galanin and is available on Bitbucket.

The mount-zip project was then forked from fuse-zip in 2021 and further developed by François Degros. The ability to write and modify ZIP archives has been removed, but a number of optimizations and features have been added 🌈:

Read-Write Mode — mount-zip: ❌ · fuse-archive: ❌ · fuse-zip: ✅
Read-Only Mode — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ✅
Format Support — mount-zip: ZIP · fuse-archive: Wide · fuse-zip: ZIP
GPG Encryption — mount-zip: ❌ · fuse-archive: ✅ · fuse-zip: ❌
Native ZIP Encryption — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ✅
Lazy Decompression — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ❌
Default Caching — mount-zip: Lazy · fuse-archive: Pre-emptive · fuse-zip: N/A
Memory Caching — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ✅
Temp File Caching — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ❌
Handles Huge Files — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ❌
Sparse File Detection — mount-zip: ❌ · fuse-archive: ✅ · fuse-zip: ❌
Precision Timestamps — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ✅
Several Archives — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ❌
Automatic Mount Point — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ❌
FUSE 3 Support — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ❌
Distinct Error Codes — mount-zip: ✅ · fuse-archive: ✅ · fuse-zip: ❌

👑 AUTHORS 👑

François Degros
Alexander Galanin

Legends, both of them.

💜 LICENSE 💜

mount-zip is released under the GNU General Public License Version 3 or later.

🌸 SEE ALSO 🌸

fuse-archive(1), fuse-zip(1), fusermount(1), fuse(8), umount(8)

And that's the whole page, bestie — go mount something ✨

mount-zip 1.16 · August 2026 · MOUNT-ZIP(1) 🎀

📦 where this page comes from

nixos 26.05: mount-zip 1.16
nixpkgs unstable: mount-zip 1.16
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms