Version 1.2.0 built on 2025-08-16

Feature

• Add optional hidden folder control interface <mount point>/.ratarmount-control/.
• Add capability to mount into relative subpaths in existing FUSE mount using the control interface.
• Use rich for help formatting, logging, and the progress bar if installed.
• Enable mfusepy and other backend debug output for high --debug settings.
• --recursive will now also join split files and descend into the resulting file.
• Add --no-file-versions for disabling the file version layer.
  One fewer layer may improve performance and reduce problems.
• Offer --no-xxx variants for all bool flags.
• Move all command line options that are actually subcommands into an exclusive group.

Performance

• Store gzip indexes as compressed gztool index. Gztool indexes are compressed.
  A novel sparsing method is used to increase compressibility by doing a sparsity analysis
  and setting all unneeded window bytes to 0. This reduces the index size for large gzips by 10-20x.
  This also reduces memory consumption because the gzip index is fully held in memory.

API

• Drop support for EOL Python 3.7 and 3.8. Older ratarmount versions are still available on old Python versions.

ratarmountcore

Fixes

• Make fsspec ratar:// protocol implementation return full paths on ls so that AbstractFileSystem.find works.

AppImages

The AppImages can be downloaded, made executable with chmod u+x *.AppImage, and executed directly to start ratarmount.

There are also usability helpers for AppImages such as AppImageLauncher and AM.

If the AppImage is too slow to start up or to reduce memory overhead for the AppImage itself, the AppImage can also be manually unpacked and installed:

• Extract with ratarmount-*.AppImage --appimage-extract
• The extracted AppImage can be started by executing squashfs-root/AppRun.
• Rename and move the resulting generic squashfs-root folder wherever you want, e.g., /opt/ratarmount-<version>.
• Add a link to /opt/ratarmount-<version>/AppRun into some folder that is in your PATH variable, e.g., with:
  ln -s /opt/ratarmount-<version>/AppRun ~/.local/bin/ratarmount

Slim Version

Supports: 7z, ASAR, bzip2, EXT4, FAT, gzip, RAR, SQLAR, TAR, XZ, ZIP, zlib, ZStandard

Normal / Full Version

Supports:

• All slim formats
• libarchive backend: ar, CAB, cpio, grzip, ISO9660, lrzip, LZ4, lzip, LZMA, lzop, RPM, UU, WARC, XAR, Z
• SquashFS
• All remote protocols: ftp://, git://, http://, ssh://, ...
• Colored output
• Ships with compiled Python bytecode to speed up startup latency by 2-3x at the cost of 20% larger AppImage size.

ratarmount

Fixes

• Fix wrong sys.executable in AppImage and make AppRun POSIX-compliant to not require bash on the host.
• Improve handling of non-existent input files in argument check.
• Properly clean up the log file on exit.
• Standard error output redirection with --log-file did not work.

ratarmountcore

Fixes

• Querying compositing mount sources with an empty string instead of / did not work correctly.
• SQLARMountSource: Files with denormal paths did show empty mount points.
• SQLARMountSource: Also mention cryptography module if missing.
• SQLiteIndexMountSource: Do not delete SQLite files that are not ratarmount indexes.
• Add join_threads to SingleFileMountSource and FileVersionLayer to avoid hangs when this call is not forwarded.
• SubvolumesMountSource: __exit__ did not correctly delegate to held mount sources.
• SubvolumesMountSource: Normalize path returned by get_mount_source.
• SubvolumesMountSource: Return subvolume root for direct folder access.

AppImages

The AppImages can be downloaded, made executable with chmod u+x *.AppImage, and executed directly to start ratarmount.

There are also usability helpers for AppImages such as AppImageLauncher and AM.

If the AppImage is too slow to start up or to reduce memory overhead for the AppImage itself, the AppImage can also be manually unpacked and installed:

• Extract with ratarmount-*.AppImage --appimage-extract
• The extracted AppImage can be started by executing squashfs-root/AppRun.
• Rename and move the resulting generic squashfs-root folder wherever you want, e.g., /opt/ratarmount-<version>.
• Add a link to /opt/ratarmount-<version>/AppRun into some folder that is in your PATH variable, e.g., with:
  ln -s /opt/ratarmount-<version>/AppRun ~/.local/bin/ratarmount

Slim Version

Supports: 7z, ASAR, bzip2, EXT4, FAT, gzip, RAR, SQLAR, TAR, XZ, ZIP, zlib, ZStandard

Normal / Full Version

Supports:

• All slim formats
• libarchive backend: ar, CAB, cpio, grzip, ISO9660, lrzip, LZ4, lzip, LZMA, lzop, RPM, UU, WARC, XAR, Z
• SquashFS
• All remote protocols: ftp://, git://, http://, ssh://, ...
• Ships with compiled Python bytecode to speed up startup latency by 2-3x at the cost of 20% larger AppImage size.

ratarmount

Fixes

• Fix possible issue when deleting from write overlay.
• Do not filter chained fsspec protocols as unknown protocol.
• Return the correct number of blocks for files. This fixes results from du.
• Improve automatic mount point inference.

ratarmountcore

Fixes

• Python file object implementations did not return True for closed after closing them.
• Patch broken TAR parsing for >8 GiB file with sparsity.
• Patch wrong checksum for >8 GiB file with sparsity.
• Support files larger than 8 GiB for GNU sparse detection.
• Fix very long parsing time during GNU sparse detection with --ignore-zeros.
• Make @overrides a test-time error not a runtime-error.
• Make fsspec tar:// protocol work. For most cases, this should be avoided, though, because it does not
  use the performance benefits of ratarmount.
• Use exceptions over asserts for functional SQLAR magic bytes checks so that it works with python3 -O
  optimization mode.
• Detect Zstandard files created by pzstd, which start with a skippable frame.
• Show the correct permissions for the archives opened via libarchive.

AppImages

The AppImages can be downloaded, made executable with chmod u+x *.AppImage, and executed directly to start ratarmount.

There are also usability helper for AppImages such as AppImageLauncher and AM.

If the AppImage is too slow to start up or to reduce memory overhead for the AppImage itself, the Appimage can also be manually unpacked and installed:

• Extract with ratarmount-*.AppImage --appimage-extract
• The extracted AppImage can be started by executing squashfs-root/AppRun.
• Rename and move the resulting generic squashfs-root folder wherever you want, e.g., /opt/ratarmount-<version>.
• Add a link to /opt/ratarmount-<version>/AppRun into some folder that is in your PATH variable, e.g., with:
  ln -s /opt/ratarmount-<version>/AppRun ~/.local/bin/ratarmount

Slim Version

Supports: 7z, ASAR, bzip2, EXT4, FAT, gzip, RAR, SQLAR, TAR, XZ, ZIP, zlib, ZStandard

Normal / Full Version

Supports:

• all slim formats
• libarchive (ar, CAB, cpio, grzip, ISO9660, lrzip, LZ4, lzip, LZMA, lzop, RPM, UU, WARC, XAR, Z), SquashFS
• all remote protocols (ftp://, git://, http://, ssh://, ...)

ratarmount

Features

• Add support for argument completion in your shell with argcomplete if it is installed.
• Make --unmount accept multiple mount points to unmount.
• Add support for extended file attributes.
• Extract libfuse3 support into mfusepy, a fork of fusepy, and depend on it.
• Add --log-file option to write output to file when daemonized.

Performance

• Try backends in smarter order based on file suffix.

ratarmountcore

Feature

• Add support for SQLAR SQLite archives.
• Add support for mounting .index.sqlite ratarmount indexes directly without the associated archive-
• Add support for encrypted 7z files via py7zr.
• Add support for EXT4 images.
• Add support for SAR archives.
• Add new method to specify fine-granular parallelization for each backend.
• Make --recursion-depth 0 only undo the compression on TAR files.
• Show better error message when trying to open supported file formats with missing Python modules.
• Libarchive: Add warning when file contents are encrypted and no password specified.

Performance

• Do not import everything in main module to aid some delayed import workflows for smaller latencies.

API

• Rename AutoMountLayer.recursionDepth to maxRecursionDepth.
• Restructure ratarmountcore file hierarchy. Move MountSource implementations into subfolders.
• Use snake_case for functions and class methods, one step further towards PEP 8.
• Accept os.PathLike in open_mount_source.

Fixes

• The progress bar was wrong for parallelized XZ decompression.
• Collect correct file permissions for SquashFS, RAR, ZIP, and Libarchive.
• FileVersionLayer: Do not dispatch requests on .versions folder to underlying mount source.
• AutoMountLayer: Account for recursions depths introduced by SQLiteIndexedTar.
• Mounting github:// without a prefix did not work correctly.
• Avoid misdetection of images as TAR by libarchive.
• SubvolumeMountSource: Return clone of root file info to avoid duplicate userdata elements.

AppImages

The AppImages can be downloaded, made executable with chmod u+x *.AppImage, and executed directly to start ratarmount.

There are also usability helper for AppImages such as AppImageLauncher and AM.

If the AppImage is too slow to start up or to reduce memory overhead for the AppImage itself, the Appimage can also be manually unpacked and installed:

• Extract with ratarmount-*.AppImage --appimage-extract
• The extracted AppImage can be started by executing squashfs-root/AppRun.
• Rename and move the resulting generic squashfs-root folder wherever you want, e.g., /opt/ratarmount-<version>.
• Add a link to /opt/ratarmount-<version>/AppRun into some folder that is in your PATH variable, e.g., with:
  ln -s /opt/ratarmount-<version>/AppRun ~/.local/bin/ratarmount

Slim version

Supports: 7z, ASAR, bzip2, EXT4, FAT, gzip, RAR, SQLAR, TAR, XZ, ZIP, zlib, ZStandard

Normal / Full Version

Supports:

• all slim formats
• libarchive (ar, CAB, cpio, grzip, ISO9660, lrzip, LZ4, lzip, LZMA, lzop, RPM, UU, WARC, XAR, Z), SquashFS
• all remote protocols (ftp://, git://, http://, ssh://, ...)

This is the newest as of yet unreleased but tested state.
Try this if you have trouble with other versions or you want cutting edge features.

ratarmount

Semantic versioning of GUIs and CLIs is not easy to define. The simplest GUI usage has not changed since the first version and even the index file format has been mostly compatible since version 0.2.0 and there is a lot of code for version checking. Based on the semver FAQ, the 1.0.0. release should probably have been a long time ago. Here it is now!

Features

• Bundle modified fusepy in order to add libfuse3 support in case only that one is installed.
  Contributions to the mfusepy fork would be welcome!
• Add message for first time users to show the result mount point.

Performance

• Disable Python-side buffering when opening files via FUSE.
• Forward underlying archive block sizes to statfs and stat implementations.

Fixes

• statfs did not work when using a write overlay and calling it on a file not in the overlay folder.
• Union mounting of inputs with the same name, even if in different folders, ignored all but the first.
• Suppress teardown warning in case the mount source was not even created yet.
• Make mounting work with only a write overlay.
• Avoid hangs and errors caused by non-joined threads before forking into the background by checking for running threads.
• Set locale to C when calling GNU tar to get more reproducible output on --commit-overlay.

ratarmountcore

Features

• Add fsspec implementation and register it as ratar://.
• Add support for new formats: SquashFS, Git, FAT12, FAT16, FAT32.
• Add support for fsspec backends. Archives and even index files can now be specified via URIs:
  dropbox://, ftp://, git://, github://, http://, https://, ipfs://, ipns://, s3://, ssh://, sftp://, smb://, webdav://.
• Add support for remote and compressed index files. Ratarmount will automatically look for
  index files with .gz and other common extensions and extracts these into /tmp/ or RATARMOUNT_INDEX_TMPDIR
  before using them.
• MountSource.open: Add buffering argument to enable/disable buffering or set the buffer size.

Fixes

• Argument to --gzip-seek-point-spacing was ignored when using the rapidgzip backend.
• Index creation did not work with default arguments with an archive in a read-only location.
• Close sqlite3 dummy connection after querying the SQLite version.
• Avoid resource leaks in case a MountSource constructor throws.
• SQLiteIndex: Do note store checkMetadata callback as a member to avoid dependency cycles.
• SQLiteIndex: Ignore errors when the connection is already closed.
• SQLiteIndexedTar: Avoid resource leak when constructor fails.

Performance

• Import compiled zip decrypter for 100x speedup for Standard ZIP 2.0 encrypted ZIP files
• Speed up readdir and therefore simple use cases such as find to iterate all files and folders by 3x.
• Avoid reading the whole appended TAR parts into memory for the check has-been-appended-to check.
• Fix block size being ignored when reading everything via io.BufferedReader.
• Do not use parallelization with possibly huge prefetches for simple file type checks.

ratarmount

The AppImage now uses manylinux_2_28 instead of manylinux2014 because CentOS 7 was EOL 2024-06-30, which broke the Github Actions pipeline for building the AppImage because some of the "actions" such as "checkout" broken because they are using npm, which requires a newer glibc version and does not work anymore inside the manylinux2014 container. I tried to manually check out the repo, which worked, but then I lost my patience when the upload-artifact action also failed.

Fixes

• Setting either the owner or group for a file with --write-overlay would reset the group or user respectively.
• Setting owner or group to 0 (root) with --write-overlay was not working.

ratarmountcore

Fixes

• Fix error when combining --recursive or --recursion-depth with --write-overlay.

ratarmount

Fixes

• Show install suggestions when FUSE is missing.
• File deletion with --commit-overlay did not work.

ratarmountcore

Fixes

• Fix the missing indentation for the index version check.
• Make --help and --version work even if libarchive.so is not installed.
• Fix LibarchiveMountSource compatibility issues with older libarchive versions.
• Fix the exception in StenciledFile when seeking before the file start.

ratarmount

Added

• Print indicators for versions of loaded shared libraries.

ratarmountcore

Added

• Add libarchive backend and detection support for:
  grzip, lrzip, lz4, lzip, lzma, lzop, rpm, uuencode, compress, 7zip, ar, cab, deb, xar, cpio, iso, war, cxar.
• Add --transform option to map each archive entry path via a regex to some user-specified one.
• Add zlib support (RFC1950).
• Store backend name into the index and check that the index fits to the current backend / MountSource.
• Store isGnuIncremental flag in the index.
• Apply specified priorities for opening all archives not just gzip.

Performance

• Determine incremental archives from index rows to avoid seeks.
• Remove indexed_bzip2 dependency in favor of rapidgzip, which in the future should support even more formats.

Fixes

• utils.findModuleVersion: Return version not name if __version__ does not exist.

rapidgzip

Added

• The rapidgzip Python library now also bundles IndexedBzip2File from indexed_bzip2.
• Enable checksum verification by default.
• Support for decompression from non-seekable inputs such as stdin.

Performance

• Windows / seek points are compressed in memory for reduced memory usage.
• Avoid doubling memory usage during index import and export by streaming the data directly to the output file.

ratarmount

Fixes

• Do not check mount point because of faulty os.path.ismount, simply try fusermount.
• Avoid total I/O hang when lazy-mounting a folder with archives onto itself.

ratarmountcore

Fixes

• Return a valid file info and file version count for /.
• Make the original archive viewable as an older file version when using AutoMountLayer.
• Resolve symbolic links pointing outside the source folder given to FolderMountSource to not break them.
• Do not return a valid FileInfo for invalid paths such as ../...
• Make --index-minimum-file-count work for the TAR backend.
• The index should not be created for very small archives.
• Root file info userdata was not initialized correctly.
• Index validation did fail for TAR entries with more than 2 metadata blocks.
• Do not check for folder consistency because parent folders get automatically added to the index.
• Move _createFileInfo out of MountSource class to fix "protected-access" warning.
• Joined files (a.001, a.002) did not work because of an accidentally shared list.
• Do not check file header for zip, only for the footer, to detect self-extracting archives.