# Ratarmount: browse a tarball as a folder, and seek inside compressed streams

> Ratarmount indexes the file positions inside a TAR and mounts it read-only through FUSE, so an archive becomes a browsable folder without extraction. It supports true random access inside gzip, bzip2, xz, and zstd streams, recursive mounting of archives inside archives, union mounts, a write overlay, and remote backends through filesystem_spec.

**mxmlnkn/ratarmount** — Access large archives as a filesystem efficiently, e.g., TAR, RAR, ZIP, GZ, BZ2, XZ, ZSTD archives

- Repository: https://github.com/mxmlnkn/ratarmount
- Stars: 1,324 · Forks: 50
- Language: Python
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/mxmlnkn-ratarmount

## Index first, then mount

Ratarmount collects all file positions inside a TAR so that it can easily jump to and read from any file without extracting it. It then mounts the TAR using mfusepy, a fork of fusepy, for read access just like archivemount.

The order of those two operations is the design. Indexing a TAR means walking its headers once and recording, for every member, the byte offset at which its data begins. That index is what makes the mount fast, because when something opens a file in the mounted folder, the filesystem layer looks up the offset and seeks there rather than reading through the archive from the start.

For an uncompressed TAR, the index is a straightforward header walk. For a compressed one, the problem is harder, and that is where the project's distinguishing work sits.

The project states the capability precisely: care was taken to achieve fast random access inside compressed streams for bzip2, gzip, xz, and zstd, and inside TAR files, by building indices containing seek points.

A seek point in a compressed stream is not the same thing as a byte offset. Gzip and bzip2 in particular are not seekable in the way a plain file is, so a seek point records a position in the compressed stream plus the state of the decompressor at that point, so that decompression can resume there. Building those seek points is the expensive part, and it is what the index building phase does before the mount appears.

The project contrasts itself with libarchive, on which archivemount is based, noting that in contrast to libarchive, random access and true seeking is supported. And it contrasts itself with tarindexer, which also collects file positions for random access, in that ratarmount offers easy access via FUSE and support for compressed TARs.

## Recursive mounting, union mounts, and a write overlay

The capability list is where the project stops being a simple archive browser and starts being a filesystem tool.

Recursive mounting means ratarmount will also mount TARs inside TARs inside TARs, recursively into folders of the same name, and the project names the use case: this is useful for the 1.31TB ImageNet data set. That is a concrete, demanding example. A dataset that large cannot be extracted, and a dataset structured as archives of archives is exactly the case where a plain tar listing is not enough and where you need each nested archive to appear as a directory you can descend into.

Mount compressed files covers the case where the file is compressed but is not a TAR. You can leverage ratarmount's true seeking capabilities when opening the mounted uncompressed view of such a file, so a raw .gz or .xz of a single large file becomes randomly accessible through the mount.

Read-only bind mounting lets folders be mounted read-only to other folders, and the stated use case is merging a backup TAR with newer versions of those files residing in a normal folder. That is the shape of a restore: the archive is the base, the working directory has the recent edits, and the merged view is what you inspect.

Union mounting generalises that: multiple TARs, compressed files, and bind mounted folders can be mounted under the same mountpoint.

The write overlay is the most interesting of the set, and it is the one with real consequences. A folder can be specified as write overlay, all changes below the mountpoint will be redirected to this folder, and deletions are tracked so that all changes can be applied back to the archive. So the mount is writable, but nothing is written into the archive itself. Changes land in a separate directory, deletions are remembered, and the intent is that you can later apply them back to the archive. That is a copy-on-write model with a reconciliation step, and it is much safer than a writable mount that silently modifies your tarball.

The other capability is remote files. A remote archive or whole folder structure can be mounted similar to tools like sshfs, thanks to the filesystem_spec project, and the supported protocols are listed: FTP, HTTP, HTTPS, SFTP, SSH, Git, Github, S3, Samba v2 and v3, Dropbox, and more. The project is candid that many of these are very experimental and may be slow, and it asks for a feature request if further backends are desired.

## The command line is one argument, and the syntax is uniform

The examples in the project's README are the fastest way to understand the interface, because every command has the same shape.

`ratarmount archive.tar.gz` mounts a compressed archive at a folder called `archive` and makes its contents browsable. `ratarmount --recursive archive.tar mountpoint` mounts the archive and recursively all its contained archives under a folder called `mountpoint`. `ratarmount folder mountpoint` bind-mounts a folder. `ratarmount folder1 folder2 mountpoint` bind-mounts a merged view of two or more folders under `mountpoint`. `ratarmount folder archive.zip folder` mounts a merged view of a folder on top of archive contents.

The pattern is that the last argument is the mountpoint and everything before it is a source. With one source you get a plain mount, with several you get a union mount, and the `--recursive` flag extends the whole thing into nested archives. There is no separate verb for merging, no separate verb for recursion, and no separate verb for remote.

The option syntax follows the FUSE convention rather than inventing its own, and the one example shows it: `ratarmount -o modules=subdir,subdir=squashfs-root archive.squashfs mountpoint` mounts an archive subfolder `squashfs-root` under `mountpoint`.

Remote sources are given as URIs, and the examples show the range. `ratarmount http://server.org:80/archive.rar folder folder` mounts an archive accessible via HTTP range requests, which is the mechanism that makes a remote archive seekable rather than a download. `ratarmount ssh://hostname:22/relativefolder/ mountpoint` mounts a folder hierarchy via SSH, and a second SSH example shows a path with a double slash for an absolute path. `ratarmount github://mxmlnkn:ratarmount@v0.15.2/tests/ mountpoint` mounts a GitHub repo as if it were checked out at the given tag, SHA, or branch, which is a neat trick that turns a repository reference into a filesystem path.

The S3 example shows the credentials in the environment:

```bash
AWS_ACCESS_KEY_ID=01234567890123456789 AWS_SECRET_ACCESS_KEY=0123456789012345678901234567890123456789 ratarmount s3://127.0.0.1/bucket/single-file.tar mounted
```

The comment on that line notes that bogus credentials may be necessary for unsecured endpoints, because some S3-compatible servers ignore the signature and still serve the object.

The `-P <cores>` option controls the parallelism, and the default is that all cores are used for parallelized algorithms such as the gzip, bzip2, and xz decoders, which can yield huge speedups on most modern processors but requires more main memory.

## Why random access inside a compressed stream is hard

The project has a table of contents entry for the problem and another for the solution, which tells you the maintainer considers the underlying problem worth explaining.

The reason it matters is that compression and seeking pull in opposite directions. A compressed stream is a sequence where each byte depends on the bytes before it, which is exactly what makes it small. To read the middle of the stream you normally have to decompress everything before it. The classic solution, and the one ratarmount's seek points use, is to record a set of positions in the compressed stream from which decompression can restart, and to store enough decompressor state at each of them to make the restart valid.

That is why the index is built up front and why the build phase is the expensive part. The cost of a mount with random access is a full pass over the archive to build the index, and the benefit is that every subsequent read is a seek rather than a rescan.

This is also the reason the tool distinguishes itself from libarchive. The project links to a section of the libarchive documentation titled notes about the library design, and the distinction it draws is that random access and true seeking is supported, in contrast to libarchive. libarchive is a streaming library with a strong format coverage, and it is a reasonable choice when you are reading an archive once, sequentially. It is a poor choice when the consumer of the archive is a filesystem, because a filesystem does not know in advance which file it will be asked for next, and every open has to be cheap.

That is the framing that makes ratarmount a filesystem tool rather than an archive tool. Its consumer is the kernel, through FUSE, and the kernel's access pattern is random and unpredictable, which is why the index and the seek points are built for that pattern rather than for streaming.

The random access capability is listed specifically for bzip2, gzip, xz, and zstd, and for TAR files. The other archive formats the project supports are listed separately in the supported formats page, so the set of formats you can read is wider than the set for which the seeking guarantee holds.

## Packaging is thorough, and the build pins setuptools carefully

The installation table of contents has six entries, which is a good sign for a tool that has to run on other people's machines.

There is an AppImage, package manager installation with Arch Linux called out, a note on system dependencies for pip installation described as rarely necessary, pip package installation, argument completion, and a graphical user interface. The GUI in particular is notable for a FUSE tool, because a command line tool that mounts filesystems benefits enormously from a file picker.

The pyproject.toml shows the kind of care that goes into a project with a long life. The build requirements are `setuptools >= 61, < 83` and `wheel`, and each constraint has a comment explaining it. The comment on the upper bound says to use setuptools up to 82 because the license specification changes backward-incompatible in 2026-02, with a link to the setuptools issue. The comment on the lower bound says not to use the major-only form for pinning, because it will only match major.0.0 and not any higher version.

That is a build pin with a reason attached, which is the difference between a pin and an arbitrary constraint.

The project metadata records the name as `ratarmount` with the description Random Access To Archived Resources, the licence as MIT with the matching OSI classifier, and the author as Maximilian Knespel. The development status is 4 - Beta, and the operating system classifiers are MacOS and Unix.

The Python classifiers list 3.9 through 3.12, and there is a comment explaining a decision that is unusual and honest: the author is unsure about the semantics of listing versions in the classifiers, notes that they are only informational, and says that older Python versions do not work with the current version of the project but older installable versions of the project exist for them, so listing them is fine.

The repository layout has `core/`, `ratarmount/`, `tests/`, `benchmarks/`, `docs/`, and an `AppImage/` directory. There is a `CHANGELOG.md` in Markdown, a `LICENSE`, and a Zenodo DOI badge for the project.

The release history shows steady work: v1.2.2 in March 2026, v1.2.3 in April 2026, and v1.3.0 in May 2026, with the last push on 2026-10-15.

## Where Ratarmount is the wrong tool

The limits are clear and they are about the class of problem this solves.

First, and most simply, if the archive is small, extract it. The cost of a ratarmount invocation is an indexing pass over the archive, a FUSE mount, and a daemon-like process, and for a 200 megabyte tarball that is a lot of machinery for something `tar xf` does in the same time. The tool earns its cost at the scale where extraction is expensive, which is exactly the case the project names with the 1.31TB ImageNet data set.

Second, FUSE is a hard requirement and it is not available everywhere. Many managed sandboxes, some container setups, and several cloud environments do not permit FUSE mounts or do not expose `/dev/fuse`. On those systems ratarmount simply does not work, and there is no fallback in the design because the whole model is a filesystem mount.

Third, the read-only assumption is doing a lot of work in the examples. The primary mode is a read access mount, and the write overlay is a distinct, more elaborate feature with its own semantics, where changes are redirected to a folder and deletions are tracked for later application back to the archive. If you need a mount where writes land in the archive itself, that is not what this does.

Fourth, the remote backends are explicitly experimental. The project says many of them are very experimental and may be slow. HTTP range requests work because they give you the seeking primitive. Other protocols, particularly the object stores, may be slow for the index-building phase, and the S3 example's note that bogus credentials may be necessary suggests the level of polish in that path is limited.

Fifth, the memory cost of parallelism is a real trade. By default all cores are used for the parallelised decoders, which can yield huge speedups on most modern processors but requires more main memory. On a machine with many cores and a constrained memory budget, the default may be the wrong choice, and the `-P <cores>` option is the control.

Sixth, and this is the scope question, ratarmount reads archives. It does not edit them. There is no equivalent of a tar command for modifying an archive in place, and the write overlay is a way to collect changes for later application, not a live editing environment.

## Conclusion

Ratarmount fits a data pipeline that reads a handful of files out of a very large archive, a training set that ships as tarballs, and an environment where FUSE is available and the archive is too big to extract. It is the wrong tool for a small archive, where extraction is simpler, and it is the wrong tool where FUSE is not permitted, such as many managed sandboxes. Check three things before you rely on it: that your environment allows FUSE mounts, that the compression scheme you use is one of the ones with real random access support, and that you read the write overlay semantics carefully, because the deletions are tracked so changes can be applied back to the archive later, which is a workflow rather than a transparent write-through.

## FAQ

### How does Ratarmount mount a TAR archive?

It collects all file positions inside the TAR so it can jump to and read any file without extracting, then mounts the TAR using mfusepy, a fork of fusepy, for read access. The basic invocation is `ratarmount archive.tar.gz`, which mounts a compressed archive at a folder called `archive`.

### Which compression formats support true random access in Ratarmount?

Care was taken to achieve fast random access inside compressed streams for bzip2, gzip, xz, and zstd, and inside TAR files, by building indices containing seek points. This is in contrast to libarchive, on which archivemount is based, which does not support random access and true seeking.

### What are Ratarmount's union mounting and write overlay features?

Multiple TARs, compressed files, and bind mounted folders can be mounted under the same mountpoint as a union mount. A folder can be specified as write overlay, so all changes below the mountpoint are redirected to that folder and deletions are tracked, allowing the changes to be applied back to the archive later.

### Can Ratarmount mount remote archives and folders?

Yes, thanks to the filesystem_spec project, similar to how sshfs works. Supported protocols include FTP, HTTP, HTTPS, SFTP, SSH, Git, Github, S3, Samba v2 and v3, and Dropbox, and the project notes that many of these are very experimental and may be slow.

## Sources

- [Issues](https://github.com/mxmlnkn/ratarmount/issues)
- [License: MIT](https://github.com/mxmlnkn/ratarmount/blob/master/LICENSE)
- [mxmlnkn/ratarmount on GitHub](https://github.com/mxmlnkn/ratarmount)
- [README](https://github.com/mxmlnkn/ratarmount/blob/master/README.md)
- [Releases](https://github.com/mxmlnkn/ratarmount/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mxmlnkn-ratarmount