mount-zip.1

'\" t
.\" Automatically generated by Pandoc 3.1.11.1
.\"
.TH "MOUNT\-ZIP" "1" "February 2026" "mount\-zip 1.13" "User Manual"
.SH NAME
\f[B]mount\-zip\f[R] \- Mount ZIP archives as FUSE file systems.
.SH SYNOPSIS
.IP \[bu] 2
\f[B]mount\-zip\f[R] [\f[I]options\f[R]] \f[I]zip\-file\f[R]
.IP \[bu] 2
\f[B]mount\-zip\f[R] [\f[I]options\f[R]] \f[I]zip\-file\f[R]
\f[I]mount\-point\f[R]
.IP \[bu] 2
\f[B]mount\-zip\f[R] [\f[I]options\f[R]] \f[I]zip\-file\-1\f[R]
\f[I]zip\-file\-2\f[R] \&...
\f[I]mount\-point\f[R]
.SH DESCRIPTION
\f[B]mount\-zip\f[R] mounts one or several ZIP archives as a read\-only
\c
.UR https://en.wikipedia.org/wiki/Filesystem_in_Userspace
FUSE file system
.UE \c
\&.
It starts quickly, uses little memory, decodes encrypted files, and
provides on\-the\-go decompression and caching for maximum efficiency.
.PP
\f[B]mount\-zip\f[R] automatically creates the target mount point if
needed.
If no mount point is specified, \f[B]mount\-zip\f[R] creates a mount
point in the current working directory.
.SH OPTIONS
.TP
\f[B]\-\-help\f[R] or \f[B]\-h\f[R]
Print help.
.TP
\f[B]\-\-version\f[R] or \f[B]\-V\f[R]
Print program version.
.TP
\f[B]\-o quiet\f[R] or \f[B]\-q\f[R]
Print fewer log messages.
.TP
\f[B]\-o verbose\f[R] or \f[B]\-v\f[R]
Print more detailed log messages.
.TP
\f[B]\-o redact\f[R]
Redact file names from log messages.
.TP
\f[B]\-o force\f[R]
Continue even if the given password is wrong or missing, or if the
encryption or compression method is unsupported.
.TP
\f[B]\-o precache\f[R]
Preemptively decompress and cache the whole ZIP archive(s).
.TP
\f[B]\-o cache=DIR\f[R]
Use a different cache directory (default is \f[CR]$TMPDIR\f[R] or
\f[CR]/tmp\f[R]).
.TP
\f[B]\-o memcache\f[R]
Cache the decompressed data in memory.
.TP
\f[B]\-o nocache\f[R]
Do not cache the decompressed data.
.TP
\f[B]\-o encoding=CHARSET\f[R]
Original encoding of file names.
.TP
\f[B]\-o notrim\f[R]
Do not trim the base of the tree.
Keep all the intermediate directories as specified in the ZIP
archive(s).
.TP
\f[B]\-o nomerge\f[R]
Do not merge multiple ZIP archives on top of each other.
Instead, create a subdirectory for each ZIP archive inside the mount
point.
.TP
\f[B]\-o nodirs\f[R]
No directories.
Flatten the archive structure by presenting all its files in its root
directory.
This might make sense if you\[cq]re not interested in the archive tree
structure, but only in its file data, e.g.\ for malware scanning.
.TP
\f[B]\-o nospecials\f[R]
Hide special files (FIFOs, sockets, devices).
.TP
\f[B]\-o nosymlinks\f[R]
Hide symbolic links.
.TP
\f[B]\-o nohardlinks\f[R]
Hide hard links.
.TP
\f[B]\-o dmask=M\f[R]
Directory permission mask in octal (default 0022).
.TP
\f[B]\-o fmask=M\f[R]
File permission mask in octal (default 0022).
.TP
\f[B]\-o uid=N\f[R]
Set the user ID of all the items in the mounted archive (default is
current user).
.TP
\f[B]\-o gid=N\f[R]
Set the group ID of all the items in the mounted archive (default is
current group).
.TP
\f[B]\-o default_permissions\f[R]
Use the user ID, group ID and permissions stored with each item in the
archive.
.TP
\f[B]\-f\f[R]
Foreground mode.
.TP
\f[B]\-d\f[R]
Foreground mode with debug output.
.SH USAGE
Mount a ZIP archive:
.IP
.EX
$ mount\-zip foobar.zip mnt
.EE
.PP
The mounted ZIP archive can be explored and read using any application:
.IP
.EX
$ tree mnt
mnt
└── foo

0 directories, 1 file

$ cat mnt/foo
bar
.EE
.PP
When finished, unmount the file system:
.IP
.EX
$ umount mnt
.EE
.SH FEATURES
.IP \[bu] 2
Read\-only view
.IP \[bu] 2
Instant mounting, even with big ZIP archives
.IP \[bu] 2
Compression methods: deflate, bzip2
.IP \[bu] 2
Encryption methods: AES and legacy ZIP encryption
.IP \[bu] 2
Asks for decryption password if necessary
.IP \[bu] 2
Detects file name encoding
.IP \[bu] 2
Converts file names to Unicode UTF\-8
.IP \[bu] 2
Deduplicates files in case of name collisions
.IP \[bu] 2
Unpacks files when reading them (on\-the\-go decompression)
.IP \[bu] 2
Supports all file types, including named sockets, FIFOs, block and
character devices, symbolic links and hard links
.IP \[bu] 2
Supports Unix access modes and DOS file permissions
.IP \[bu] 2
Supports owner and group information (UID and GID)
.IP \[bu] 2
Supports relative and absolute paths
.IP \[bu] 2
Supports high precision timestamps
.IP \[bu] 2
Works on 32\-bit and 64\-bit devices
.IP \[bu] 2
Supports ZIP64 extensions, even on 32\-bit devices:
.RS 2
.IP \[bu] 2
Supports ZIP archives containing more than 65,535 files
.IP \[bu] 2
Supports ZIP archives and files bigger than 4 GB
.RE
.IP \[bu] 2
Supports the following ZIP format extensions:
.RS 2
.IP \[bu] 2
000A PKWARE NTFS high\-precision timestamps
.IP \[bu] 2
000D PKWARE Unix file type
.IP \[bu] 2
5455 Unix timestamps
.IP \[bu] 2
5855 Info\-ZIP Unix extra fields (type 1)
.IP \[bu] 2
7855 Info\-ZIP Unix extra fields (type 2)
.IP \[bu] 2
7875 Info\-ZIP Unix extra fields (type 3): UID and GID
.RE
.SS File Name Encoding
\f[B]mount\-zip\f[R] is fully Unicode compliant.
It converts the file names stored in the ZIP archive from their original
encoding to UTF\-8.
.PP
In order to interpret these file names correctly, \f[B]mount\-zip\f[R]
needs to determine their original encoding.
By default \f[B]mount\-zip\f[R] tries to guess this encoding using the
detection feature provided by the ICU library.
It can automatically recognize the following encodings:
.IP \[bu] 2
UTF\-8
.IP \[bu] 2
CP437
.IP \[bu] 2
Shift JIS
.IP \[bu] 2
Big5
.IP \[bu] 2
EUC\-JP
.IP \[bu] 2
EUC\-KR
.IP \[bu] 2
GB18030
.IP \[bu] 2
ISO\-2022\-CN
.IP \[bu] 2
ISO\-2022\-JP
.IP \[bu] 2
ISO\-2022\-KR
.IP \[bu] 2
KOI8\-R
.PP
For example, when mounting a ZIP containing a Shift JIS\-encoded file
name, the encoding is correctly detected:
.IP
.EX
$ mount\-zip sjis\-filename.zip mnt

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

0 directories, 1 file
.EE
.PP
This system is not foolproof, and doesn\[cq]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 \c
.UR https://en.wikipedia.org/wiki/Mojibake
Mojibake
.UE \c
:
.IP
.EX
$ mount\-zip cp866.zip mnt

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

0 directories, 2 files
.EE
.PP
In this case, the user needs to explicitly specify the original file
name encoding using the \f[CR]\-o encoding\f[R] mount option:
.IP
.EX
$ mount\-zip \-o encoding=cp866 cp866.zip mnt

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

0 directories, 2 files
.EE
.SS Name Deduplication
In case of name collision, \f[B]mount\-zip\f[R] adds a number to
deduplicate the conflicting file name:
.IP
.EX
$ 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
.EE
.PP
Directories are never renamed.
If a file is colliding with a directory, the file will be the one
getting renamed.
.SS Encrypted Archives
\f[B]mount\-zip\f[R] supports encrypted ZIP archives.
It understands the legacy ZIP encryption scheme, as well as the more
recent AES encryption schemes (AES\-128, AES\-192 and AES\-256).
.PP
When \f[B]mount\-zip\f[R] finds an encrypted file while mounting a ZIP
archive, it asks for a password.
If the given password does not decrypt the file, then
\f[B]mount\-zip\f[R] refuses to mount the ZIP archive and returns an
error:
.IP
.EX
$ 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] \[aq]/Encrypted AES\-128.txt\[aq]
Password > Got it!
Use the \-o force option to mount an encrypted ZIP with a wrong password
Cannot open File [1] \[aq]/Encrypted AES\-128.txt\[aq]: Wrong password provided
.EE
.PP
Providing the correct password allows \f[B]mount\-zip\f[R] to mount the
ZIP archive and decode the files:
.IP
.EX
$ mount\-zip different\-encryptions.zip mnt
Need password for File [1] \[aq]/Encrypted AES\-128.txt\[aq]
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.
.EE
.PP
You can force \f[B]mount\-zip\f[R] to mount an encrypted ZIP even
without providing the right password by using the \f[CR]\-o force\f[R]
option:
.IP
.EX
$ mount\-zip \-o force different\-encryptions.zip mnt
Need password for File [1] \[aq]/Encrypted AES\-128.txt\[aq]
Password > Got it!
Continuing despite wrong password because of \-o force option
.EE
.PP
In this case, the files can be listed, but trying to open an encrypted
file for which the given password doesn\[cq]t work results in an I/O
error:
.IP
.EX
$ 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: \[aq]mnt/Encrypted AES\-128.txt\[aq]: Input/output error
md5sum: \[aq]mnt/Encrypted AES\-192.txt\[aq]: Input/output error
md5sum: \[aq]mnt/Encrypted AES\-256.txt\[aq]: Input/output error
md5sum: \[aq]mnt/Encrypted ZipCrypto.txt\[aq]: Input/output error

$ cat mnt/*
This is not encrypted.
cat: \[aq]mnt/Encrypted AES\-128.txt\[aq]: Input/output error
cat: \[aq]mnt/Encrypted AES\-192.txt\[aq]: Input/output error
cat: \[aq]mnt/Encrypted AES\-256.txt\[aq]: Input/output error
cat: \[aq]mnt/Encrypted ZipCrypto.txt\[aq]: Input/output error
.EE
.PP
For security reasons, \f[B]mount\-zip\f[R] doesn\[cq]t allow the
password to be specified on the command line.
However, it is possible to pipe the password to
\f[B]mount\-zip\f[R]\[cq]s standard input:
.IP
.EX
$ echo password | mount\-zip different\-encryptions.zip mnt
Need password for File [1] \[aq]/Encrypted AES\-128.txt\[aq]
Password is Ok
.EE
.SS Symbolic links
\f[B]mount\-zip\f[R] shows symbolic links recorded in the ZIP archive:
.IP
.EX
$ mount\-zip symlink.zip mnt

$ tree mnt
mnt
├── date
└── symlink \-> ../tmp/date
.EE
.PP
Note that symbolic links can refer to files located outside the mounted
ZIP archive.
In some circumstances, these links could pose a security risk.
.PP
Symbolic links can be suppressed with the \f[CR]\-o nosymlinks\f[R]
option:
.IP
.EX
$ mount\-zip \-o nosymlinks symlink.zip mnt
Skipped Symlink [1] \[aq]/symlink\[aq]

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

0 directories, 1 file
.EE
.SS Special Files
\f[B]mount\-zip\f[R] shows special files (sockets, FIFOs or pipes,
character and block devices) recorded in the ZIP archive:
.IP
.EX
$ mount\-zip \-o default_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
.EE
.PP
Special files can be suppressed with the \f[CR]\-o nospecials\f[R]
option:
.IP
.EX
$ mount\-zip \-o default_permissions \-o nospecials pkware\-specials.zip mnt
Skipped Block Device [0] \[aq]/block\[aq]
Skipped Character Device [1] \[aq]/char\[aq]
Skipped Pipe [2] \[aq]/fifo\[aq]
Skipped Socket [4] \[aq]/socket\[aq]
Skipped Block Device [7] \[aq]/z\-hardlink\-block\[aq]
Skipped Character Device [8] \[aq]/z\-hardlink\-char\[aq]
Skipped Pipe [9] \[aq]/z\-hardlink\-fifo\[aq]
Skipped Socket [10] \[aq]/z\-hardlink\-socket\[aq]

$ ls \-n mnt
\-rw\-r\-\-r\-\- 3 1000 1000 32 Aug  9  2019 regular
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
lrwxrwxrwx 1 1000 1000  7 Aug  3  2019 z\-hardlink\-symlink \-> regular
.EE
.SS Hard Links
\f[B]mount\-zip\f[R] shows hard links recorded in the ZIP archive.
.PP
In this example, the three file entries \f[CR]0regular\f[R],
\f[CR]hlink1\f[R] and \f[CR]hlink2\f[R] point to the same inode number
(2) and their reference count is 3:
.IP
.EX
$ 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
.EE
.PP
Some tools can use the inode number to detect duplicated hard links.
In this example, \f[CR]du\f[R] 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:
.IP
.EX
$ du \-b mnt
10      mnt
.EE
.PP
Duplicated hard links can be suppressed with the
\f[CR]\-o nohardlinks\f[R] option:
.IP
.EX
$ mount\-zip \-o nohardlinks hlink\-chain.zip mnt
mount\-zip: Skipped File [1] \[aq]/hlink1\[aq]
mount\-zip: Skipped File [2] \[aq]/hlink2\[aq]

$ ls \-ni mnt
2 \-rw\-r\-\-r\-\- 1 0 0 10 Aug 14  2019 0regular
.EE
.SS File Permissions
\f[B]mount\-zip\f[R] can show the Unix file permissions and ownership
(UIDs and GIDs) as recorded in the ZIP archive when used with
\f[CR]\-o default_permissions\f[R]:
.IP
.EX
$ mount\-zip \-o default_permissions unix\-perm.zip mnt

$ ls \-n mnt
\-rw\-r\-\-\-\-\- 1 1000 1000 0 Jan  5  2014 640
\-rw\-r\-\-\-w\- 1 1000 1000 0 Jan  5  2014 642
\-rw\-rw\-rw\- 1 1000 1000 0 Jan  5  2014 666
\-rwsrwsr\-x 1 1000 1000 0 Jan  5  2014 6775
\-rwxrwxrwx 1 1000 1000 0 Jan  5  2014 777

$ md5sum mnt/*
md5sum: mnt/640: Permission denied
md5sum: mnt/642: Permission denied
d41d8cd98f00b204e9800998ecf8427e  mnt/666
d41d8cd98f00b204e9800998ecf8427e  mnt/6775
d41d8cd98f00b204e9800998ecf8427e  mnt/777
.EE
.SS Smart Caching
\f[B]mount\-zip\f[R] only does the minimum amount of work required to
serve the requested data.
When reading a compressed file, \f[B]mount\-zip\f[R] only decompresses
enough data to serve the reading application.
This is called \f[I]lazy\f[R] or \f[I]on\-the\-go\f[R] decompression.
.PP
Accessing the beginning of a big compressed file is therefore
instantaneous:
.IP
.EX
$ mount\-zip \[aq]Big One.zip\[aq] mnt

$ ls \-lh mnt/
\-rw\-rw\-r\-\- 1 root root 6.4G Mar 26  2020 \[aq]Big One.txt\[aq]

$ time head \-4 \[aq]mnt/Big One.txt\[aq]
We\[aq]re going on a bear hunt.
We\[aq]re going to catch a big one.
What a beautiful day!
We\[aq]re not scared.

real    0m0.030s
user    0m0.015s
sys     0m0.014s
.EE
.PP
\f[B]mount\-zip\f[R] generally avoids caching decompressed data.
If you read a compressed file several times, it is getting decompressed
each time:
.IP
.EX
$ dd if=\[aq]mnt/Big One.txt\[aq] of=/dev/null status=progress
6777995272 bytes (6.8 GB, 6.3 GiB) copied, 24.9395 s, 272 MB/s

$ dd if=\[aq]mnt/Big One.txt\[aq] of=/dev/null status=progress
6777995272 bytes (6.8 GB, 6.3 GiB) copied, 24.961 s, 272 MB/s
.EE
.PP
But \f[B]mount\-zip\f[R] will start caching a file if it detects that
this file is getting read in a non\-sequential way (ie the reading
application starts jumping to different positions of the file).
.PP
For example, \f[CR]tail\f[R] jumps to the end of the file.
The first time this happens, \f[B]mount\-zip\f[R] decompresses the whole
file and caches the decompressed data (in about 13 seconds in this
instance):
.IP
.EX
$ time tail \-1 \[aq]mnt/Big One.txt\[aq]
The End

real    0m12.631s
user    0m0.024s
sys     0m0.656s
.EE
.PP
A subsequent call to \f[CR]tail\f[R] is instantaneous, because
\f[B]mount\-zip\f[R] has now cached the decompressed data:
.IP
.EX
$ time tail \-1 \[aq]mnt/Big One.txt\[aq]
The End

real    0m0.032s
user    0m0.018s
sys     0m0.018s
.EE
.PP
Decompressed data is cached in a temporary file located in the cache
directory (\f[CR]$TMPDIR\f[R] or \f[CR]/tmp\f[R] by default).
The cache directory can be changed with the \f[CR]\-o cache=DIR\f[R]
option.
The cache file is only created if necessary, and automatically deleted
when the ZIP is unmounted.
.PP
Alternatively, the \f[CR]\-o memcache\f[R] option caches the
decompressed data in memory.
Be cautious with this option since it can cause \f[B]mount\-zip\f[R] to
use a lot of memory.
.PP
You can preemtively cache data at mount time by using the
\f[CR]\-o precache\f[R] option.
The cost of decompression is incurred upfront, and this ensures that any
subsequent access to the served data is fast.
.PP
If \f[B]mount\-zip\f[R] cannot create and expand the cache file, or if
it was passed the \f[CR]\-o nocache\f[R] option, it will do its best by
using a small rolling buffer in memory.
However, some data access patterns might then result in poor
performance, especially if \f[B]mount\-zip\f[R] has to repeatedly
extract the same file.
.SH PERFORMANCE
\f[B]mount\-zip\f[R] works well with large archives containing many
files.
For example on my laptop, a ZIP archive containing more than 70,000
files is mounted in half a second:
.IP
.EX
$ 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
.EE
.PP
The full contents of this mounted ZIP, totalling 1.1 GB, can be
extracted with \f[CR]cp \-R\f[R] in 14 seconds:
.IP
.EX
$ time cp \-R mnt out

real    0m13.810s
user    0m0.605s
sys     0m5.356s
.EE
.PP
For comparison, \f[CR]unzip\f[R] extracts the contents of the same ZIP
in 8.5 seconds:
.IP
.EX
$ time unzip \-q \-d out linux\-5.14.15.zip

real    0m8.411s
user    0m6.067s
sys     0m2.270s
.EE
.PP
Mounting an 8\-GB ZIP containing only a few files is instantaneous:
.IP
.EX
$ 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
.EE
.PP
Decompressing and reading the 25\-GB file from this mounted ZIP takes
less than two minutes:
.IP
.EX
$ dd if=mnt/disk of=/dev/null status=progress
26843545600 bytes (27 GB, 25 GiB) copied, 104.586 s, 257 MB/s
.EE
.PP
There is no lag when opening and reading the file, and only a moderate
amount of memory is used.
The file is getting lazily decompressed by \f[B]mount\-zip\f[R] as it is
getting read by the \f[CR]dd\f[R] program.
.SH LOG MESSAGES
\f[B]mount\-zip\f[R] records log messages into
\f[CR]/var/log/user.log\f[R].
They can help troubleshooting issues, especially if you are facing I/O
errors when reading files from the mounted ZIP.
.PP
To read \f[B]mount\-zip\f[R]\[cq]s log messages:
.IP
.EX
$ grep mount\-zip /var/log/user.log | less \-S
.EE
.PP
To follow \f[B]mount\-zip\f[R]\[cq]s log messages as they are being
written:
.IP
.EX
$ tail \-F /var/log/user.log | grep mount\-zip
.EE
.PP
Alternatively, you can run \f[B]mount\-zip\f[R] in foreground mode with
the \f[CR]\-f\f[R] option and read all the log messages on the terminal.
.PP
By default, \f[B]mount\-zip\f[R] writes INFO and ERROR messages.
You can decrease the logging level to just ERROR messages with the
\f[CR]\-o quiet\f[R] option.
Or you can increase the logging level to include DEBUG messages with the
\f[CR]\-o verbose\f[R] option:
.IP
.EX
$ mount\-zip \-f \-o verbose foobar.zip mnt
Indexing \[aq]foobar.zip\[aq]...
Allocating 16 buckets
Detected encoding UTF\-8 with 15% confidence
Indexed \[aq]foobar.zip\[aq] in 0 ms
Mounted \[aq]foobar.zip\[aq] on \[aq]mnt\[aq] in 2 ms
Reader 1: Opened File [0]
Reader 1: Closed
Unmounting \[aq]foobar.zip\[aq] from \[aq]mnt\[aq]...
Unmounted \[aq]foobar.zip\[aq] in 0 ms
.EE
.PP
To prevent file names from being recorded in \f[B]mount\-zip\f[R]\[cq]s
log messages, use the \f[CR]\-o redact\f[R] option:
.IP
.EX
$ 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
.EE
.SH RETURN VALUE
\f[B]mount\-zip\f[R] returns distinct error codes for different error
conditions related to the ZIP archives themselves:
.TP
\f[B]0\f[R]
Success.
.TP
\f[B]1\f[R]
Generic error code for: missing argument, unknown option, unknown file
name encoding, mount point cannot be created, mount point is not empty,
etc.
.TP
\f[B]11\f[R]
An archive is a multipart ZIP.
.TP
\f[B]15\f[R]
A ZIP archive cannot be read.
.TP
\f[B]19\f[R]
A ZIP archive cannot be found.
.TP
\f[B]21\f[R]
A ZIP archive cannot be opened.
.TP
\f[B]23\f[R]
Decompression error.
This is probably the sign of a wrong password.
Use \f[CR]\-o force\f[R] to bypass the password verification.
.TP
\f[B]26\f[R]
Unsupported compression method.
Use \f[CR]\-o force\f[R] to bypass the compression method verification.
.TP
\f[B]29\f[R]
An archive is not recognized as a valid ZIP.
.TP
\f[B]31\f[R]
A ZIP archive has an inconsistent structure.
.TP
\f[B]34\f[R]
Unsupported encryption method.
Use \f[CR]\-o force\f[R] to bypass the encryption method verification.
.TP
\f[B]36\f[R]
Password needed.
A ZIP archive contains an encrypted file, but no password was provided.
Use \f[CR]\-o force\f[R] to bypass the password verification.
.TP
\f[B]37\f[R]
Wrong password.
A ZIP archive contains an encrypted file, and the provided password does
not decrypt it.
Use \f[CR]\-o force\f[R] to bypass the password verification.
.TP
\f[B]45\f[R]
Possibly truncated or corrupted ZIP archive, as detected by
\f[B]libzip\f[R] 1.11 or higher.
.SH PROJECT HISTORY
\f[B]mount\-zip\f[R] started as a fork of \f[B]fuse\-zip\f[R].
.PP
The original \f[B]fuse\-zip\f[R] project was created in 2008 by \c
.UR http://galanin.nnov.ru/~al/
Alexander Galanin
.UE \c
\ and is available on \c
.UR https://bitbucket.org/agalanin/fuse-zip
Bitbucket
.UE \c
\&.
.PP
The \f[B]mount\-zip\f[R] project was then forked from
\f[B]fuse\-zip\f[R] in 2021 and further developed by \c
.UR https://github.com/fdegros
François Degros
.UE \c
\&.
The ability to write and modify ZIP archives has been removed, but a
number of optimisations and features have been added:
.PP
.TS
tab(@);
l c c.
T{
Feature
T}@T{
mount\-zip
T}@T{
fuse\-zip
T}
_
T{
Read\-Write Mode
T}@T{
❌
T}@T{
✅
T}
T{
Read\-Only Mode
T}@T{
✅
T}@T{
✅
T}
T{
Shows Symbolic Links
T}@T{
✅
T}@T{
✅
T}
T{
Shows Hard Links
T}@T{
✅
T}@T{
✅
T}
T{
Shows Special Files
T}@T{
✅
T}@T{
✅
T}
T{
Shows Precise Timestamps
T}@T{
✅
T}@T{
✅
T}
T{
Random Access
T}@T{
✅
T}@T{
✅
T}
T{
Can Cache Data in Memory
T}@T{
✅
T}@T{
✅
T}
T{
Can Cache Data in Temp File
T}@T{
✅
T}@T{
❌
T}
T{
Smart Caching
T}@T{
✅
T}@T{
❌
T}
T{
Decompresses Data Lazily
T}@T{
✅
T}@T{
❌
T}
T{
Handles Huge Files
T}@T{
✅
T}@T{
❌
T}
T{
Handles Encrypted Files
T}@T{
✅
T}@T{
❌
T}
T{
Handles Name Collisions
T}@T{
✅
T}@T{
❌
T}
T{
Detects Name Encoding
T}@T{
✅
T}@T{
❌
T}
T{
Can mount several ZIPs
T}@T{
✅
T}@T{
❌
T}
T{
Can Hide Symlinks
T}@T{
✅
T}@T{
❌
T}
T{
Can Hide Hard Links
T}@T{
✅
T}@T{
❌
T}
T{
Can Hide Special Files
T}@T{
✅
T}@T{
❌
T}
T{
Can Redact Log Messages
T}@T{
✅
T}@T{
❌
T}
T{
Can Use FUSE 3
T}@T{
✅
T}@T{
❌
T}
T{
Returns Distinct Error Codes
T}@T{
✅
T}@T{
❌
T}
.TE
.SH AUTHORS
.IP \[bu] 2
\c
.UR https://github.com/fdegros
François Degros
.UE \c
.IP \[bu] 2
\c
.UR http://galanin.nnov.ru/~al/
Alexander Galanin
.UE \c
.SH LICENSE
\f[B]mount\-zip\f[R] is released under the GNU General Public License
Version 3 or later.
.SH SEE ALSO
fuse\-archive(1), fuse\-zip(1), fusermount(1), fuse(8), umount(8)