gotorrent

README

go-torrent

A focused, composable BitTorrent protocol library for Go 1.24+.

[!NOTE] This library implements the core BitTorrent protocol (BEP 3) with a clean, package-per-concern design. No reflection. No global state. Pure stdlib.

Packages

Package	Import path	Description
bencode	github.com/natalie-o-perret/go-torrent/bencode	Bencoding encoder and decoder
bitfield	github.com/natalie-o-perret/go-torrent/bitfield	Compact bitfield for piece tracking
metainfo	github.com/natalie-o-perret/go-torrent/metainfo	.torrent file parser and InfoHash computation
tracker	github.com/natalie-o-perret/go-torrent/tracker	HTTP tracker announce client
peer	github.com/natalie-o-perret/go-torrent/peer	Peer wire protocol (handshake, messages)
piece	github.com/natalie-o-perret/go-torrent/piece	Per-piece download state and verification

Quick start

import (
    "os"

    "github.com/natalie-o-perret/go-torrent/metainfo"
    "github.com/natalie-o-perret/go-torrent/tracker"
)

// Parse a .torrent file
f, _ := os.Open("ubuntu.torrent")
defer f.Close()

m, err := metainfo.Decode(f)
if err != nil {
    // handle
}

fmt.Println(m.Info.Name)    // e.g. "ubuntu-24.04-desktop-amd64.iso"
fmt.Println(m.InfoHash)     // hex SHA-1 of the info dict

// Announce to the first tracker
peers, err := tracker.Announce(m.Trackers()[0], tracker.AnnounceRequest{
    InfoHash: m.InfoHash,
    Left:     m.Info.TotalLength(),
    NumWant:  50,
})

CLI

go install github.com/natalie-o-perret/go-torrent/cmd/gotorrent@latest

gotorrent info ubuntu.torrent

Example output:

Name:         ubuntu-24.04-desktop-amd64.iso
InfoHash:     e4be9e4db876e3e3179778b03e906297be5c8dbe
Piece length: 524288 bytes
Pieces:       4560
Total size:   2392997888 bytes
Announce:     https://torrent.ubuntu.com/announce
Trackers:
  https://torrent.ubuntu.com/announce
  https://ipv6.torrent.ubuntu.com/announce

Protocol coverage

BEP	Description	Status
BEP 3	The BitTorrent Protocol Specification	Core packages
BEP 23	Tracker Returns Compact Peer Lists	tracker

License

MIT — see LICENSE.

Documentation

Overview

Package gotorrent is a BitTorrent protocol library and CLI for Go 1.24+.

It provides focused, composable packages implementing the core BitTorrent specification (BEP 3) and related extensions.

Packages

bencode: Encoder and decoder for the bencoding format used in .torrent files and tracker responses -- supports int64, string, []byte, []any, and map[string]any.

bitfield: Compact byte-slice bitfield for tracking which pieces a peer has downloaded, with O(1) Has/Set and an O(n) popcount.

metainfo: Parser for .torrent files -- extracts the Info struct, computes the 20-byte SHA-1 InfoHash, and provides the flat tracker URL list.

tracker: HTTP tracker client -- constructs announce requests and parses compact and dictionary peer responses.

peer: BitTorrent peer wire protocol -- handshake (BEP 3), length-prefixed message framing, and helpers for the Request and Piece message types.

piece: Per-piece download state machine -- block-level request tracking, data accumulation, and SHA-1 hash verification.