anacrolix/torrent: A Go BitTorrent Library for Streaming and Embedding

What anacrolix/torrent Is Actually For

This is not a torrent application. It is a Go module that implements BitTorrent packages and command-line utilities, and the README states the emphasis plainly: "The emphasis is on use as a library from other projects." The README also says it has been used 24/7 in production by downstream services since late 2014, and that the implementation was created to explore Go's concurrency capabilities and to stream data directly from the BitTorrent network.

The audience follows from that. If you are writing a Go service that needs to fetch or seed torrents, or that needs to read a file inside a torrent before the download finishes, this is the layer you build on. If you want to double-click a .torrent file and watch a progress bar, you are not the audience; the README's downstream list is where those live.

The streaming angle is the part that distinguishes it from a plain downloader. The README says it "supports seeking, readaheads and other features" and exposes torrents and their files through Go's io package interfaces, with torrentfs as the demonstration.

How the Library Exposes Torrents as Readers

The mechanism visible in the README is a client object plus per-torrent file handles that satisfy Go's io interfaces. You create a client from a config, add torrents to it, and then read. Because the file handles are readers with seek support, a caller can jump to an offset and the library will fetch the pieces it needs, rather than requiring a complete download first. That is what makes the streaming use case work, and it is also why the storage layer matters: a backend that cannot serve random reads cheaply will undermine the whole design.

The README lists several storage backends provided: blob, file, bolt, mmap, and sqlite, among others. It also documents an interface, storage.ClientImpl, for writing your own backend, with S3 and databases named as examples. This is the most consequential design decision in the project. Storage is pluggable, so the choice of where pieces live is yours, and so is the cost of getting it wrong.

On the network side, the README states support for protocol encryption, DHT, PEX, uTP, WebTorrent, WebSeeds, BitTorrent v2, holepunching, and "many more features and BEPs". It does not enumerate them in the README; it points to the package documentation on pkg.go.dev, which is where the actual API surface lives. Treat the README as a signpost and the package docs as the reference.

Installing anacrolix/torrent and Reading a Torrent

The README gives two install paths. For the library, `go get github.com/anacrolix/torrent`. For the bundled commands, `go install github.com/anacrolix/torrent/cmd/...@latest`. The README notes that installing by import path runs in Go's module-aware mode and ignores the repository's go.work file, so it works without checking out any git submodules. That is the path most users want.

go get github.com/anacrolix/torrent
go install github.com/anacrolix/torrent/cmd/...@latest

If you instead clone and build from the checkout, the workspace file is in play. The README warns that go.work adds the possum storage backend, which is vendored as a git submodule at storage/possum/lib, and that building from a clone requires the submodule to be checked out. The error it quotes is specific:

cannot load module storage/possum/lib/go listed in go.work file: open storage/possum/lib/go/go.mod: no such file or directory

So clone with submodules, or initialize them afterwards.

git clone --recurse-submodules https://github.com/anacrolix/torrent
git submodule update --init --recursive

The README offers `GOWORK=off` as an alternative, with the caveat that the possum storage backend will not be available. For a first real use, the README's own example is routing peer connections through a SOCKS5 proxy. It starts from the default config, disables the built-in peer dialer so the SOCKS5 dialer is the only one used for outgoing peer connections, then adds the dialer:

cfg := torrent.NewDefaultClientConfig()
cfg.DialForPeerConns = false
cl, _ := torrent.NewClient(cfg)
cl.AddDialer(dialer.NewSocks5("localhost:1080", nil))

The README is explicit that the proxy applies to outgoing peer connections and that listening for incoming connections is unaffected. That is a useful first exercise because it touches config, client construction, and the dialer package in a few lines. Beyond this, the README points to small examples in the package documentation on pkg.go.dev rather than reproducing them.

The go.work and possum Constraint

The submodule requirement is the sharpest practical edge in the README. A contributor who clones the repository the ordinary way and runs `go build ./...` gets a failure, not a warning. The README states this directly and quotes the error text. The fix is either `git clone --recurse-submodules`, `git submodule update --init --recursive` in an existing clone, or `GOWORK=off`.

The trade-off in that third option is stated: with the workspace disabled, the possum storage backend is unavailable. So there is a real difference between building the library for consumption and building the repository for development, and the README does not pretend otherwise. If possum matters to you, you need the submodule and you need the Rust toolchain, because the Dockerfile installs rustup and the justfile's build-possum recipe runs `cargo build` inside storage/possum/lib. That is a heavier build dependency than a pure Go project would have.

Note also that the justfile sets CGO_LDFLAGS to include a link path under storage/possum/lib/target/debug, and the Dockerfile sets GOWORK=off before copying and building. The two files are making different choices about the workspace, which is worth knowing before you copy either one as a template.

Where anacrolix/torrent Is the Wrong Tool

The README does not document a stable command-line interface for end users. The commands exist under cmd/, and the install line is `go install github.com/anacrolix/torrent/cmd/...@latest`, but the README does not walk through any of them, does not show flags, and does not describe what each command does. If your requirement is a downloader you can hand to someone who does not write Go, this repository is not it, and the README effectively says so by listing downstream projects instead.

There is a second limitation in the structure of the library itself. Because storage is pluggable and the README names blob, file, bolt, mmap, sqlite and custom backends without recommending one, the project pushes a decision onto you that a finished client would have made already. Choosing badly shows up as slow seeks or disk pressure, and the README gives no guidance on which backend suits which workload. That is a documentation gap, not a defect, but it is a real cost of adoption.

The README also does not document rollback, versioning policy for the library API, or a support window. There is a CHANGELOG.md and the README points to it for "a detailed list of changes by version", but no compatibility promise is stated in the README. If you depend on this module, pin a version and read the changelog yourself.

Alternatives and the Difference in Approach

The README's own downstream list is the fairest basis for comparison, because those projects made a different choice about the same problem. confluence is described as a torrent client exposed as an HTTP service. If you want torrents over HTTP rather than as a Go library, confluence is the shape you want, and the README lists it as a downstream project rather than a competitor. The difference is the interface: HTTP versus Go function calls.

TorrServer is described as a torrent streaming server over HTTP, and hTorrent as an HTTP to BitTorrent gateway with seeking support. Both offer seeking, which is the feature anacrolix/torrent is built around, but they expose it over a network protocol instead of through io.Reader. distribyted takes a third route: the README says it exposes torrent files as FUSE, WebDAV or HTTP endpoints and downloads on demand, using a fixed amount of disk space. That is a genuinely different storage strategy from the pluggable backends here.

If your program is Go and you want the torrent inside your process, none of those substitutes for the library. If your program is anything else, one of them probably does, and you avoid the go.work and possum build chain entirely.

Maintenance, Licence and Upgrade Cost

The repository is not archived, and the last push was on 2026-09-21. The README states the implementation has been used 24/7 in production by downstream services since late 2014, which describes downstream usage rather than a maintenance commitment from the maintainers.

The licence is MPL-2.0, stated in the repository metadata and present as a LICENSE file at the top level. MPL-2.0 is file-level copyleft. In practical terms for an adopter: modifications you make to files covered by the licence carry obligations, and the licence is not the permissive MIT or Apache-2.0 that many Go teams assume by default. This is not legal advice; if you are embedding this in a product, have someone who can read the licence read it.

Upgrade cost is dominated by the dependency graph rather than the module itself. The go.mod declares go 1.25.0 and pulls in a long list of anacrolix packages alongside pion/webrtc, prometheus/client_golang, and a SQLite adapter, among others. Several of those are pinned to pseudo-versions rather than tagged releases, which means upgrades move you along commit history rather than between release tags. The README does not document a deprecation policy for the library API. Plan to pin, and read CHANGELOG.md before bumping.

Editorial conclusion

Adopt it if you are writing Go and want torrents exposed as io.Reader, or if you need a storage backend you control. Do not adopt it if you want a finished end-user downloader with a GUI: the README points at downstream projects for that. Verify the go.work and possum submodule behaviour in your build environment first.

Frequently asked questions

Official sources

1. anacrolix/torrent on GitHub
2. Issues
3. License: MPL-2.0
4. README