BTFS: Mount a Torrent File as a Read-Only Filesystem

What BTFS Does and Who It Is For

BTFS mounts a .torrent file or a magnet link as a read-only directory in the local file tree. Once mounted, the contents of the torrent appear as ordinary files and directories. Applications can open, read, and copy them using standard filesystem calls. The README lists `ls`, `cat`, `cp`, `vlc`, and `mplayer` as examples of tools that work without any modification.

The download mechanism is on-demand: file content is fetched over BitTorrent only when an application actually reads a byte range. This makes BTFS useful for streaming video from a torrent, inspecting archive contents without downloading the full torrent, or scripting operations that need to read specific files from a large torrent.

A First Mount and Unmount

The basic usage requires a mount point directory and a torrent file:

mkdir mnt
btfs video.torrent mnt

After that, the mount point behaves as a directory. To unmount and stop BTFS:

fusermount -u mnt

On macOS, the unmount command is `umount mnt` rather than `fusermount -u mnt`, since macFUSE uses the standard macOS unmount mechanism. The README does not document whether BTFS keeps the torrent state between mounts or restarts downloads from the beginning on each invocation; the README is silent on this.

Installing BTFS from Distribution Packages

BTFS is available in the package repositories of several major distributions. On Debian and Ubuntu:

apt-get install btfs

On Arch Linux:

pacman -S btfs

On Fedora:

dnf install fuse-btfs

On Fedora OSTree (rpm-ostree-based systems):

rpm-ostree install fuse-btfs

On openSUSE:

zypper install btfs

On macOS via Homebrew:

brew install btfs

The macOS installation requires macFUSE, which Homebrew handles as the `--cask macfuse` dependency.

Building from Source on Linux and macOS

Building from source on Debian or Ubuntu requires these dependencies: autoconf, automake, libfuse3-dev, libtorrent-rasterbar-dev, libcurl4-openssl-dev, and g++. On Ubuntu 22.04, the package names match exactly. The full build sequence is:

sudo apt-get install autoconf automake libfuse3-dev libtorrent-rasterbar-dev libcurl4-openssl-dev g++
git clone https://github.com/johang/btfs.git btfs
cd btfs
autoreconf -i
./configure
make

And optionally to install system-wide:

make install

On macOS, Homebrew provides all dependencies:

brew install --cask macfuse libtorrent-rasterbar autoconf automake pkg-config

The build steps after installing dependencies are the same as the Linux sequence above.

Architecture and the On-Demand Download Model

BTFS sits at the intersection of two systems: the FUSE kernel interface, which lets userspace programs implement filesystems, and libtorrent-rasterbar, which handles the BitTorrent protocol. When an application opens a file in the mounted directory, the kernel routes the read request through FUSE to BTFS. BTFS translates the byte range into a set of torrent pieces and requests those pieces from peers via libtorrent-rasterbar.

libcurl is listed as a build dependency, suggesting it is used for HTTP-based communication such as web seeds or HTTP tracker requests, though the README does not explain this in detail.

The filesystem is strictly read-only. There is no write path, no seeding of uploaded data beyond what libtorrent-rasterbar handles automatically, and no interactive torrent management interface. The Gentoo package is available via `emerge -av btfs`, and the Fedora OSTree (rpm-ostree) installation path is documented separately from the standard Fedora dnf path.

Limitations of a FUSE-Based Torrent Filesystem

BTFS's read-only nature is its primary constraint. It cannot be used to create or write torrents, manage a download queue, or provide seeding controls beyond what libtorrent-rasterbar does automatically.

On-demand downloading creates latency when an application seeks to a position in a file that has not been downloaded yet. Video players must buffer ahead; if a player seeks to a point far ahead in a large file, it may pause while BTFS fetches the required pieces. The README does not document a way to pre-fetch or prioritize specific pieces.

On BSD, the README states "it should work, but no promises." There is no official BSD support. The macOS path is supported through macFUSE, but macFUSE requires a kernel extension that Apple has made progressively harder to install on newer macOS versions.

BTFS Versus qBittorrent for Media Use Cases

The most common alternative for streaming torrent content is a full-featured torrent client such as qBittorrent, which supports sequential downloading and the ability to open files before the full download is complete. The difference in approach is significant: qBittorrent is a persistent application with a GUI and daemon mode that manages multiple torrents, while BTFS is a single-torrent FUSE mount that presents files to any application through the filesystem.

BTFS is the better fit when another application needs to treat torrent contents as files without any knowledge of torrents: a script, a media player pointed at a directory, or an archiver. qBittorrent's sequential download mode is more practical when seeding matters or when managing multiple downloads, since BTFS provides no management interface at all.

Editorial conclusion

BTFS is the right tool for users and developers who need to inspect or stream the contents of a torrent without downloading everything first. It is a read-only filesystem, so it cannot write, seed new data, or manage multiple torrents as a daemon. The last push was on 2026-09-13, so the project is receiving updates. Before building from source on Linux, confirm that fuse3, libtorrent-rasterbar, and libcurl4 are available; older distributions may ship fuse2 rather than fuse3, and the package name differs by distribution.

Frequently asked questions

Official sources

1. Issues
2. johang/btfs on GitHub
3. License: GPL-3.0
4. README