johang/btfs: mount a .torrent or magnet link as a read-only directory
A bittorrent filesystem based on FUSE.
At a glance
- What is it?
- BTFS is a FUSE filesystem that turns a torrent into a mounted directory, downloading pieces on demand as applications read them. It is a small C++ project with GPL-3.0 licensing and packaging for Debian, Ubuntu, Arch, Gentoo, Fedora, OpenSUSE and macOS.
- Who is it for?
- Adopt BTFS if you want to inspect or play a single torrent file without waiting for a full download, and you are comfortable with FUSE and libtorrent on your machine. Do not adopt it if you need a writable filesystem, a seeding client, or anything with a documented recovery path after an interrupted mount.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 63 days ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- johang/btfs3,976 ★ · +5
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| johang/btfs | 4k | 4k |
5 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What BTFS does that a BitTorrent client does not
A normal BitTorrent client gives you a progress bar and a directory of files that fills up over time. BTFS gives you a directory that is already complete from the filesystem's point of view. The README states that you can mount any .torrent file or magnet link and then use it as any read-only directory in your file tree, with the contents downloaded on demand as they are read by applications. That sentence is the whole product.
The audience is narrow and specific. It is for someone who has a torrent and wants to look at one file inside it, or play one video, without committing to the full transfer. The README names ls, cat and cp as tools that work as expected, and vlc and mplayer as applications that work without changes. Those are ordinary programs reading ordinary files. Nothing in them knows a torrent is involved.
The mechanism: FUSE on top of libtorrent
BTFS is a userspace filesystem. The kernel forwards file operations to a FUSE daemon, and that daemon is a C++ program linked against libtorrent. When an application opens a file inside the mount and reads a byte range, the read arrives at the BTFS process, which asks libtorrent for the pieces covering that range and returns the data once they arrive. The read blocks until the pieces are available; the application sees a slow file, not a missing one.
This explains the read-only design. Writing would mean deciding what a modified piece means for the swarm, and the README makes no such claim. It also explains why the mount is only as good as the swarm: a read of a range that no peer has will stall the calling process. The README says the contents are downloaded on demand as they are read, and that is the entire data flow it documents. There is no cache directory, no resume file and no configuration surface described anywhere in the README.
Installing BTFS and mounting a first torrent
The README lists packages for several distributions. On Debian and Ubuntu the package is btfs; on Arch it is btfs via pacman; on Gentoo it is btfs via emerge; on Fedora the package is named fuse-btfs, and Fedora OSTree uses rpm-ostree with the same name; on OpenSUSE it is btfs via zypper; on macOS it is btfs via Homebrew.
# apt-get install btfsOn macOS the README gives a single command.
$ brew install btfsThe usage example in the README is three lines: create a mount point, run btfs with a torrent file and the mount point, then change into it.
$ mkdir mnt
$ btfs video.torrent mnt
$ cd mnt
$ vlc video.mp4After the cd, the directory listing should show the files inside the torrent. Opening video.mp4 in vlc should start playback, with the player pulling data through the mount as it decodes. Unmounting is done with fusermount, which the README shows without a path prefix.
$ fusermount -u mntIf you are building from git rather than installing a package, the README gives the Debian/Ubuntu dependency list as autoconf, automake, libfuse3-dev, libtorrent-rasterbar-dev, libcurl4-openssl-dev and g++, followed by autoreconf -i, ./configure and make. On macOS the dependency command is brew install --cask macfuse libtorrent-rasterbar autoconf automake pkg-config, and the build steps are the same. The runtime dependencies listed for Linux are fuse3, libtorrent and libcurl.
Where BTFS is the wrong tool
The read-only nature is not a footnote, it is a boundary. If your workflow involves writing into the mounted tree, renaming files, or extracting an archive in place, BTFS cannot do it, and the README never suggests otherwise.
The bigger gap is operational. The README documents mounting and unmounting and nothing else. It does not document what happens when the daemon dies mid-read, whether a partially fetched file can be resumed, where libtorrent keeps its state, or how to configure peer discovery, ports or rate limits. None of those keys appear in the README. For a filesystem that depends on a live swarm, that is a thin manual. A stalled read with no timeout configured at the filesystem level can hang the calling process, and the README gives no guidance on that either.
It is also the wrong tool for bulk work. Mounting a torrent to copy every file out is slower than letting a client download it normally, because BTFS is fetching on the read path rather than ahead of it. The on-demand model pays off when you touch a small part of a large torrent, and costs you when you touch all of it.
How BTFS differs from FUSE filesystems that stream
The closest comparison in this space is a FUSE filesystem that exposes a remote store over HTTP or a cloud API, such as rclone's mount mode. The difference is the source of truth. Those tools read from a server that already holds the bytes; BTFS reads from a swarm that holds pieces, and the pieces have to be assembled before the read returns. The failure modes differ accordingly: an HTTP-backed mount fails when the network or the credentials fail, while a BTFS mount fails when the swarm is slow or a piece is unavailable.
A second comparison is simply running a BitTorrent client and waiting. That approach is more predictable, gives you progress and resume behaviour, and works with every client's configuration options. BTFS trades that predictability for immediacy on the first bytes. Neither is strictly better; they serve different questions. If you are asking whether a torrent contains a file worth keeping, BTFS answers faster.
Maintenance, packaging and licence
The repository is not archived, and the last push was on 2026-09-13. That is recent, but the repository has no published releases, so there is no version history to read. Packaging is the practical maintenance signal: btfs is carried by Debian, Ubuntu, Arch, Gentoo, Fedora, OpenSUSE and Homebrew according to the README, which means distribution maintainers are doing the packaging work and you get upgrades through your normal package manager rather than from the project directly. When you build from git, you own the upgrade path, and the dependency list is three libraries that move independently.
The licence is GPL-3.0. If you link BTFS into another program or redistribute a modified binary, the GPL's obligations apply to that combined work. If you only run it on your own machine, the licence does not constrain your use. This is not legal advice; check with your own counsel before shipping anything built on the source.
Editorial conclusion
Adopt BTFS if you want to inspect or play a single torrent file without waiting for a full download, and you are comfortable with FUSE and libtorrent on your machine. Do not adopt it if you need a writable filesystem, a seeding client, or anything with a documented recovery path after an interrupted mount. Verify first that fuse3, libtorrent and libcurl are present in the versions your distribution ships, that the mount point is empty, and how your platform unmounts FUSE mounts, since the README only shows fusermount -u mnt on Linux.
Frequently asked questions
Does BTFS work on macOS?
Yes. The README gives a Homebrew install command, brew install btfs, and a separate build path for macOS using macfuse, libtorrent-rasterbar, autoconf, automake and pkg-config as dependencies.
Can I write files into a BTFS mount?
No. The README describes the mount as a read-only directory, and the documented tools are ls, cat, cp, vlc and mplayer, all of which read. No write path is documented.
How do I unmount a BTFS filesystem?
The README shows fusermount -u mnt after changing out of the mount point. That is the Linux command it documents; the README does not give an equivalent for macOS.
What libraries does BTFS need on Linux?
The README lists fuse3, libtorrent and libcurl as runtime dependencies, with libfuse3-dev, libtorrent-rasterbar-dev and libcurl4-openssl-dev needed when building from git on Debian or Ubuntu.
Where do I download BTFS?
The README points to distribution packages rather than a download page: apt-get install btfs on Debian and Ubuntu, pacman -S btfs on Arch, emerge -av btfs on Gentoo, dnf install fuse-btfs on Fedora, zypper install btfs on OpenSUSE, and brew install btfs on macOS.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/johang-btfs)Star history chart for your README
[](https://hysenlabs.com/projects/johang-btfs)Was this useful?