# BTFS: Mount a Torrent File as a Read-Only Filesystem > BTFS is a FUSE-based filesystem that lets you mount any .torrent file or magnet link as a read-only directory on Linux or macOS. Files are downloaded on demand as applications read them, so tools like vlc, cp, and cat work without modification. **johang/btfs** — A bittorrent filesystem based on FUSE. - Repository: https://github.com/johang/btfs - Stars: 3,971 · Forks: 147 - Language: C++ - License: GPL-3.0 - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/johang-btfs ## 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: ```bash mkdir mnt btfs video.torrent mnt ``` After that, the mount point behaves as a directory. To unmount and stop BTFS: ```bash 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: ```bash apt-get install btfs ``` On Arch Linux: ```bash pacman -S btfs ``` On Fedora: ```bash dnf install fuse-btfs ``` On Fedora OSTree (rpm-ostree-based systems): ```bash rpm-ostree install fuse-btfs ``` On openSUSE: ```bash zypper install btfs ``` On macOS via Homebrew: ```bash 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: ```bash 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: ```bash make install ``` On macOS, Homebrew provides all dependencies: ```bash 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. ## 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. ## FAQ ### How do I mount a torrent with BTFS? Create a directory for the mount point, then run `btfs video.torrent mnt`. Files appear in the mnt directory and are downloaded on demand as they are read. To unmount, run `fusermount -u mnt`. ### What dependencies does BTFS require? BTFS requires fuse3, libtorrent-rasterbar, and libcurl. On Ubuntu 22.04, the packages are fuse3, libtorrent-rasterbar8, and libcurl4. On macOS, macFUSE and libtorrent-rasterbar are available via Homebrew. ### Does BTFS work on macOS? Yes. The README documents macOS installation via Homebrew with `brew install btfs`, which installs macFUSE as a dependency. macFUSE requires a kernel extension that must be approved in macOS System Preferences. ## Sources - [Issues](https://github.com/johang/btfs/issues) - [johang/btfs on GitHub](https://github.com/johang/btfs) - [License: GPL-3.0](https://github.com/johang/btfs/blob/master/LICENSE) - [README](https://github.com/johang/btfs/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/johang-btfs