aiobt
Pure Python asyncio BitTorrent client library.
Features
- Fully async — built on
asynciofrom 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 —
ClientEventandTorrentEventenums with parent bubbling - Torrent creation — build
.torrentfiles 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
typealiases,match,TaskGroup, frozen dataclasses - Type-safe — fully typed with
py.typedmarker, 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logRelease 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 logSecurity 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.
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 logA 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.