## File: README.md # torrent [](https://pkg.go.dev/github.com/anacrolix/torrent) This repository implements BitTorrent-related packages and command-line utilities in Go. The emphasis is on use as a library from other projects. It's been used 24/7 in production by downstream services since late 2014. The implementation was specifically created to explore Go's concurrency capabilities, and to include the ability to stream data directly from the BitTorrent network. To this end it [supports seeking, readaheads and other features](https://pkg.go.dev/github.com/anacrolix/torrent#Reader) exposing torrents and their files with the various Go idiomatic `io` package interfaces. This is also demonstrated through [torrentfs](#torrentfs). There is support for [protocol encryption, DHT, PEX, uTP, WebTorrent, WebSeeds, BitTorrent v2, holepunching, and many more features and BEPs](https://pkg.go.dev/github.com/anacrolix/torrent). There are [several data storage backends provided](https://pkg.go.dev/github.com/anacrolix/torrent/storage): blob, file, bolt, mmap, and sqlite, to name a few. You can [write your own](https://pkg.go.dev/github.com/anacrolix/torrent/storage#ClientImpl) to store data for example on S3, or in a database. Some noteworthy package dependencies that can be used for other purposes include: * [go-libutp](https://github.com/anacrolix/go-libutp) * [dht](https://github.com/anacrolix/dht) * [bencode](https://pkg.go.dev/github.com/anacrolix/torrent/bencode) * [tracker](https://pkg.go.dev/github.com/anacrolix/torrent/tracker) ## Changelog See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes by version. ## Installation Install the library package with `go get github.com/anacrolix/torrent`, or the provided cmds with `go install github.com/anacrolix/torrent/cmd/...@latest`. Installing by import path like this runs in Go's module-aware mode and ignores the repository's `go.work` file, so it works without checking out any git submodules. ## Building from a checkout The repository includes a Go workspace (`go.work`) that adds the [`possum`](https://github.com/anacrolix/possum) storage backend. `possum` is vendored as a git submodule at `storage/possum/lib`, and the workspace references the Go module inside it (`storage/possum/lib/go`). Building from a clone of this repository (for example `go build ./...`) therefore requires the submodule to be checked out, otherwise Go fails with an error like: cannot load module storage/possum/lib/go listed in go.work file: open storage/possum/lib/go/go.mod: no such file or directory Check out the submodules when cloning: git clone --recurse-submodules https://github.com/anacrolix/torrent or, in an existing clone: git submodule update --init --recursive Alternatively, disable the workspace by setting `GOWORK=off`, though the `possum` storage backend won't be available in that case. ## Library examples There are some small [examples](https://pkg.go.dev/github.com/anacrolix/torrent#pkg-examples) in the package documentation. ## Mentions * [@anacrolix](https://github.com/anacrolix) is interviewed about this repo in [Console 32](https://console.substack.com/p/console-32). ### Downstream projects There are several web-frontends, sites, Android clients, storage backends and supporting services among the known public projects: * [confluence](https://github.com/anacrolix/confluence): torrent client as a HTTP service * [Gopeed](https://github.com/GopeedLab/gopeed): Gopeed (full name Go Speed), a high-speed downloader developed by Golang + Flutter, supports (HTTP, BitTorrent, Magnet) protocol, and supports all platforms. * [bitmagnet](https://github.com/bitmagnet-io/bitmagnet): A self-hosted BitTorrent indexer, DHT crawler, content classifier and torrent search engine with web UI, GraphQL API and Servarr stack integration. * [Erigon](https://github.com/ledgerwatch/erigon): an implementation of Ethereum (execution layer with embeddable consensus layer), on the efficiency frontier. * [Mangayomi](https://github.com/kodjodevf/mangayomi): Cross-platform app that allows users to read manga and stream anime from a variety of sources including BitTorrent. * [autobrr](https://github.com/autobrr/autobrr): autobrr redefines download automation for torrents and Usenet, drawing inspiration from tools like trackarr, autodl-irssi, and flexget. * [TorrServer](https://github.com/YouROK/TorrServer): Torrent streaming server over http * [exatorrent](https://github.com/varbhat/exatorrent): Elegant self-hostable torrent client * [distribyted](https://github.com/distribyted/distribyted): Distribyted is an alternative torrent client. It can expose torrent files as a standard FUSE, webDAV or HTTP endpoint and download them on demand, allowing random reads using a fixed amount of disk space. * [Simple Torrent](https://github.com/boypt/simple-torrent): self-hosted HTTP remote torrent client * [mabel](https://github.com/smmr-software/mabel): Fancy BitTorrent client for the terminal * [Toru](https://github.com/sweetbbak/toru): Stream anime from the terminal! * [hTorrent](https://github.com/pojntfx/htorrent): HTTP to BitTorrent gateway with seeking support. * [webtor.io](https://webtor.io/): free cloud BitTorrent-client * [Android Torrent Client](https://gitlab.com/axet/android-torrent-client): Android torrent client * [libtorrent](https://gitlab.com/axet/libtorrent): gomobile wrapper * [CortexFoundation/torrentfs](https://github.com/CortexFoundation/torrentfs): Independent HTTP service for file seeding and P2P file system of cortex full node * [Go-PeersToHTTP](https://github.com/WinPooh32/peerstohttp): Simple torrent proxy to http stream controlled over REST-like api * [Torrent WebDAV Client](https://github.com/Jipok/torrent-webdav): Automatic torrent download, streaming, WebDAV server and client. #### Inactive / historical * [Go Peerflix](https://github.com/Sioro-Neoku/go-peerflix): Start watching the movie while your torrent is still downloading! * [ANT-Downloader](https://github.com/anatasluo/ant): ANT Downloader is a BitTorrent Client developed by golang, angular 7, and electron * [goTorrent](https://github.com/deranjer/goTorrent): torrenting server with a React web frontend * [Remote-Torrent](https://github.com/BruceWangNo1/remote-torrent): Download Remotely and Retrieve Files Over HTTP * [Trickl](https://github.com/arranlomas/Trickl): torrent client for android * [Elementum](http://elementum.surge.sh/) (up to version 0.0.71) ## Help Communication about the project is primarily through [Discussions](https://github.com/anacrolix/torrent/discussions) and the [issue tracker](https://github.com/anacrolix/torrent/issues). ## Command packages Here I'll describe what some of the packages in `./cmd` do. See [installation](#installation) to make them available. ### `torrent` #### `torrent download` Downloads torrents from the command-line. $ torrent download 'magnet:?xt=urn:btih:KRWPCX3SJUM4IMM4YF5RPHL6ANPYTQPU' ... lots of jibber jabber ... downloading "ubuntu-14.04.2-desktop-amd64.iso": 1.0 GB/1.0 GB, 1989/1992 pieces completed (1 partial) 2015/04/01 02:08:20 main.go:137: downloaded ALL the torrents $ md5sum ubuntu-14.04.2-desktop-amd64.iso 1b305d585b1918f297164add46784116 ubuntu-14.04.2-desktop-amd64.iso $ echo such amaze wow #### `torrent metainfo magnet` Creates a magnet link from a torrent file. Note the extracted trackers, display name, and info hash. $ torrent metainfo testdata/debian-10.8.0-amd64-netinst.iso.torrent magnet magnet:?xt=urn:btih:4090c3c2a394a49974dfbbf2ce7ad0db3cdeddd7&dn=debian-10.8.0-amd64-netinst.iso&tr=http%3A%2F%2Fbttracker.debian.org%3A6969%2Fannounce See `torrent metainfo --help` for other metainfo related commands. ### `torrentfs` torrentfs mounts a FUSE filesystem at `-mountDir`. The contents are the torrents described by the torrent files and magnet links at `-metainfoDir`. Data for read requests is fetched only as required from the torrent network, and stored at `-downloadDir`. $ mkdir mnt torrents $ torrentfs -mountDir=mnt -metainfoDir=torrents & $ cd torrents $ wget http://releases.ubuntu.com/14.04.2/ubuntu-14.04.2-desktop-amd64.iso.torrent $ cd .. $ ls mnt ubuntu-14.04.2-desktop-amd64.iso $ pv mnt/ubuntu-14.04.2-desktop-amd64.iso | md5sum 996MB 0:04:40 [3.55MB/s] [========================================>] 100% 1b305d585b1918f297164add46784116 - --- ## File: bencode/README.md Bencode encoding/decoding sub package. Uses similar API design to Go's json package. ## Install ```sh go get github.com/anacrolix/torrent ``` ## Usage See the [package example](https://pkg.go.dev/github.com/anacrolix/torrent/bencode#example-package) in the documentation.