Skip to main content

aiobt

Pure Python asyncio BitTorrent client library.

Features

  • Fully async — built on asyncio from the ground up with an async context manager interface
  • Zero dependencies — pure stdlib, no runtime dependencies
  • BEP 3 wire protocol — full handshake, piece exchange, tit-for-tat choking algorithm
  • Multi-tracker — BEP 12 tiered announce-list with automatic failover
  • HTTP + UDP trackers — BEP 3 HTTP and BEP 15 compact UDP announce
  • LAN peer discovery — BEP 26 Local Service Discovery via multicast
  • Endgame mode — duplicate-requests final pieces across all peers for fast completion
  • Resume persistence — save and restore download progress with SHA-1 verification
  • Pluggable storage — swap the filesystem backend for S3, databases, or anything else
  • Compact mode — store multi-file torrents as a single blob for distribution services
  • Async event system — ClientEvent and TorrentEvent enums with parent bubbling
  • Torrent creation — build .torrent files from local content with auto piece-size selection
  • DSCP traffic classification — mark BitTorrent traffic at the IP layer
  • Cython-ready — hot paths (bencode, protocol, piece) structured for optional Cython compilation
  • Modern Python — requires 3.14+, uses type aliases, match, TaskGroup, frozen dataclasses
  • Type-safe — fully typed with py.typed marker, checked with pyrefly

Installation

pip install aiobt

Quick Start

import asyncio
from aiobt import Client
from aiobt.storage import DiskStorage

async def main() -> None:
    storage = DiskStorage("/tmp/downloads")

    async with Client(storage=storage) as client:
        handle = await client.add_torrent_file(
            "archlinux-2026.05.01-x86_64.iso.torrent",
            start=True,
        )
        print(f"Downloading: {handle.name}")
        print(f"Progress: {handle.progress:.1%}")

        # Wait for download to complete
        await handle.wait()
        print(f"Done! State: {handle.state}")

asyncio.run(main())

Events

Register callbacks for client and torrent lifecycle events. Events use enum types — no string matching:

from aiobt import Client, ClientEvent, TorrentEvent

async with Client(storage=storage) as client:

    @client.on(ClientEvent.TORRENT_COMPLETED)
    async def on_complete(handle):
        print(f"Finished: {handle.name}")

    handle = await client.add_torrent_file("linux.torrent", start=True)

    @handle.on(TorrentEvent.PIECE_VERIFIED)
    async def on_piece(handle, piece_index):
        print(f"Piece {piece_index} verified")

    @handle.on(TorrentEvent.PEER_CONNECTED)
    async def on_peer(handle, peer_addr):
        print(f"Connected to {peer_addr}")

    await handle.wait()

Torrent events bubble up to the client, so a single client-level listener covers all torrents:

@client.on(TorrentEvent.PIECE_VERIFIED)
async def on_any_piece(handle, piece_index):
    print(f"{handle.name}: piece {piece_index}")

Event Types

ClientEvent: TORRENT_ADDED, TORRENT_REMOVED, TORRENT_COMPLETED, TORRENT_ERROR

TorrentEvent: STATE_CHANGED, PIECE_VERIFIED, PEER_CONNECTED, PEER_DISCONNECTED, TRACKER_RESPONSE, TRACKER_FAILED, COMPLETED, ERROR

Resume Persistence

Downloads resume automatically after a restart. Pass state_dir to ClientConfig to enable:

from pathlib import Path
from aiobt import Client, ClientConfig
from aiobt.storage import DiskStorage

config = ClientConfig(state_dir=Path("/tmp/aiobt-state"))

async with Client(storage=DiskStorage("/tmp/downloads"), config=config) as client:
    handle = await client.add_torrent_file("large-file.torrent", start=True)
    # Progress is saved as pieces complete.
    # On restart, verified pieces are restored from disk — no re-download.
    await handle.wait()

Resume data is bencoded, stored at {state_dir}/{info_hash_hex}.resume, and written atomically. On startup, each claimed piece is SHA-1-verified against torrent data before being marked as complete.

Compact Storage for Distribution

For seeding servers or CDN nodes where you want simple file management, use CompactStorage to store even multi-file torrents as a single blob:

from aiobt import Client
from aiobt.storage import CompactStorage

async with Client(storage=CompactStorage("/srv/torrents")) as client:
    handle = await client.add_torrent_file("linux-distro.torrent", start=True)
    await handle.wait()  # All files stored as one blob on disk

Custom Storage Backends

Implement the StorageBackend protocol to plug in any storage:

from aiobt.storage import StorageBackend

class S3Storage:
    """Store torrent data in S3."""

    async def open(self, total_length: int, piece_length: int) -> None:
        self._bucket = await create_bucket()

    async def read(self, offset: int, length: int) -> bytes:
        return await self._bucket.get_range(offset, length)

    async def write(self, offset: int, data: bytes) -> None:
        await self._bucket.put_range(offset, data)

    async def close(self) -> None:
        await self._bucket.close()

Local Peer Discovery (BEP 26)

Find peers on the local network without a tracker — ideal for LAN parties, office setups, or air-gapped environments:

import asyncio
from aiobt import LocalDiscovery

async def main() -> None:
    async with LocalDiscovery(listen_port=6881) as lsd:
        # Announce a torrent we're serving
        lsd.announce(info_hash)

        # Discover peers on the LAN
        async for peer in lsd.discovered_peers():
            print(f"LAN peer: {peer.host}:{peer.port}")

asyncio.run(main())

LSD is also integrated into Client — enable it via NetworkConfig:

from aiobt import Client, ClientConfig
from aiobt.network import NetworkConfig

config = ClientConfig(network=NetworkConfig(lsd_enabled=True))
async with Client(storage=storage, config=config) as client:
    ...  # LSD runs automatically, discovered peers are connected

LocalDiscovery uses IPv4 multicast (239.192.152.143:6771) with optional IPv6 support. It automatically filters out its own announcements via a per-instance cookie.

Torrent Creation

Create .torrent files from local content:

from aiobt import create_torrent, torrent_to_bytes

meta = create_torrent(
    path="/path/to/files",
    trackers=["http://tracker.example.com/announce"],
    comment="My torrent",
)

# Write to disk
data = torrent_to_bytes(meta)
with open("my.torrent", "wb") as f:
    f.write(data)

Piece size is selected automatically based on total content size, targeting ~1,500 pieces with power-of-two sizes between 16 KiB and 16 MiB.

BEP Support

BEP Name Status
BEP 3 The BitTorrent Protocol ✅ Wire protocol, piece exchange, tit-for-tat choking
BEP 12 Multitracker Metadata Extension ✅ Tiered announce-list with shuffle and promotion
BEP 15 UDP Tracker Protocol ✅ Compact UDP announce with connection ID caching
BEP 26 Zeroconf Peer Discovery ✅ IPv4/IPv6 multicast LSD with cookie filtering

Architecture

aiobt/
├── client.py       # Client async context manager, TorrentHandle, ClientConfig
├── engine.py       # Download/upload loop, endgame mode, block assembly
├── choking.py      # BEP 3 tit-for-tat choking algorithm
├── protocol.py     # Wire protocol messages (Handshake, Choke, Request, Piece, ...)
├── peer.py         # PeerConnection TCP stream wrapper
├── piece.py        # PieceTracker with rarest-first selection
├── tracker.py      # HTTP + UDP (BEP 15) tracker announce
├── discovery.py    # Local Service Discovery — BEP 26 multicast
├── torrent.py      # Torrent metadata parsing (single/multi-file, BEP 12)
├── bencode.py      # Bencode codec (Cython-ready)
├── events.py       # Async EventEmitter with parent bubbling
├── resume.py       # Bencoded resume data persistence, atomic writes
├── create.py       # Torrent creation from files on disk
├── network.py      # DSCP, address family detection, NetworkConfig
└── storage/
    ├── base.py     # StorageBackend protocol
    ├── disk.py     # Standard multi-file on-disk storage
    ├── compact.py  # Single-blob storage for distribution
    └── queue.py    # Executor-backed filesystem I/O queue

Development

git clone https://github.com/fried/aiobt.git
cd aiobt
pip install -e ".[dev]"

# Run tests (uses later.unittest for async test support)
python -m unittest discover tests

# Format + lint
ruff format src/ tests/
ruff check src/ tests/

# Type check
pyrefly check src/

Optional Cython Compilation

The bencode, protocol, and piece modules ship with Cython variants (.pyx) that compile automatically when building from source via the Meson backend:

pip install meson-python meson ninja cython
pip install -e ".[dev]" --no-build-isolation

Verify it loaded:

from aiobt import is_compiled, compilation_status
print(compilation_status())  # {'bencode': True, 'protocol': True, 'piece': True}

Both .so and .py are always shipped — Python prefers the compiled extension but falls back to pure Python automatically.

CI / CD

  • CI runs on every push and PR: ruff formatting + lint, pyrefly type checking, pure Python tests, and Cython compile + test.
  • Release on v* tags: builds sdist and platform wheels (Linux, macOS arm64, Windows) with Cython, tests them, then publishes to PyPI via trusted publishing.

License

MIT

Metadata

Release files for aiobt 26.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiobt 26.6.2
File Size Uploaded Provenance Actions
aiobt-26.6.2.tar.gz 99.0 kB With provenance Details for aiobt-26.6.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for aiobt 26.6.2
File Interpreter ABI Platform Actions
aiobt-26.6.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.17+ x86-64 Details for aiobt-26.6.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
aiobt-26.6.2-cp314-cp314-macosx_14_0_arm64.whl CPython 3.14 CPython 3.14 macOS 14.0+ ARM64 Details for aiobt-26.6.2-cp314-cp314-macosx_14_0_arm64.whl

Total release size: 692.4 kB

Release files / aiobt-26.6.2.tar.gz

Download URL aiobt-26.6.2.tar.gz
Size 99.0 kB
Tags Source
SHA-256 checksum
How to use checksums
174135e21b043f82b48dc25adb25df33b56c3b3a47ccd64fbbeb7a0b2f1bcd15
BLAKE2b-256 checksum
How to use checksums
d21027a09495991c061e95b70eba8978f936ace8a50dbcb32ace394b0dcea0b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 3, 2026.

Transparency log

Release files / aiobt-26.6.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL aiobt-26.6.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 340.6 kB
Tags CPython 3.14 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
2470c889dafb5239a16817b5faaaf0bd3464b16da7e52eaa25c99dc4e89d0b01
BLAKE2b-256 checksum
How to use checksums
33b391d5d3522c1b42aa9ec74782f8279474984093fcade1aab6cd557301dd37
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 3, 2026.

Transparency log

Release files / aiobt-26.6.2-cp314-cp314-macosx_14_0_arm64.whl

Download URL aiobt-26.6.2-cp314-cp314-macosx_14_0_arm64.whl
Size 252.9 kB
Tags CPython 3.14 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
f9dfed2830dd5971798619cac8086e589db3aebddf1a5e1ece191249579d259a
BLAKE2b-256 checksum
How to use checksums
51392dee8274e2acb7938f773214f75d1968c61e3cf94e434bd7f0c3ab26e0fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 3, 2026.

Transparency log

Security for aiobt 26.6.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 3 files in this release have been uploaded with provenance metadata.

Select from 3 files

Attestation for aiobt-26.6.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page