aria2-rust
aria2-rust is an independent Rust download engine. It provides practical compatibility with the aria2 ecosystem so existing users and tools can migrate easily, while its architecture, safety, performance, and product direction are its own. It supports HTTP/HTTPS, FTP/SFTP, BitTorrent, Metalink, and JSON-RPC/XML-RPC/WebSocket paths; compatibility status and verification evidence are tracked in docs/compatibility-status.md.
Implemented Capabilities
The capability inventory below describes code paths, not a claim that every feature has passed the complete cross-platform E2E matrix. See the compatibility status for the current gate.
- Multi-Protocol Download: HTTP/HTTPS, FTP/SFTP, BitTorrent (DHT/PEX/MSE), Metalink V3/V4
- Multi-Source Mirrors: Automatic segmented parallel downloads from multiple URIs for maximum bandwidth utilization
- Resume Support: Breakpoint resume on all protocols with seamless recovery after network interruptions
- Full BitTorrent Support:
- ✅ DHT network (KRPC + routing table + bootstrap)
- ✅ Tracker communication (UDP/HTTP)
- ✅ Peer Exchange (PEX, per-peer BEP 10 extension-ID negotiation)
- ✅ MSE/PE encryption (BEP14 handshake)
- ✅ Choking algorithms + seed-time/ratio support
- ✅ RarestFirst piece selection
- ✅ uTP protocol (BEP 29) - Not in original aria2 C++
- ✅ Web Seeds (BEP 19)
- ✅ LPD (Local Peer Discovery)
- ✅ Complete seeding mode with upload support
- Rate Limiting: Token bucket algorithm with per-task/global limits
- Cookie Management: Netscape format persistence + auto-loading from files
- Session Management: Auto-save + manual save/load with .aria2 control files
- RPC Remote Control: JSON-RPC 2.0, XML-RPC, WebSocket (36 all-features methods, 6 notifications; compatibility coverage tracked separately)
- Configuration System: ~95 core options with four-source merging (CLI/file/environment/defaults)
- NetRC Authentication: Automatic FTP/HTTP credential loading from
.netrcfiles - URI List Files: Batch import download tasks via
-iparameter - Public Tracker List: Auto-update from trackerslist.com for BT peer discovery
Quick Start
One-Line Installation (Recommended)
Linux / macOS:
|
Windows (PowerShell):
irm https://raw.githubusercontent.com/balovess/aria2_rust/main/install.ps1 | iex
Docker:
Package Managers:
| Platform | Command |
|---|---|
| Homebrew (macOS/Linux) | brew install ./homebrew/aria2-rust.rb |
| Scoop (Windows) | scoop install ./scoop/aria2-rust.json |
| Cargo (from source) | cargo install --path aria2 |
First Download
After installation, start downloading immediately:
# Download a file
# Download with multiple connections
# Download a torrent
# Download with custom directory
Build from Source
Prerequisites:
- Rust 1.70+ (stable)
- Windows / macOS / Linux
Build Commands:
# Clone the repository
# Build all crates
# Download a file (HTTP)
# Download with custom options
# Show help
# Show version
Usage
Configuration Templates
We provide ready-to-use configuration templates in examples/configs/:
| Template | Description |
|---|---|
| minimal.conf | Minimal configuration for quick setup |
| basic.conf | Basic configuration with common options |
| advanced.conf | Advanced configuration with RPC, proxy, etc. |
| bittorrent.conf | Optimized for BitTorrent downloads |
Usage:
# Copy template to config directory
# Edit as needed
# Run with configuration
Basic HTTP Download
With Options
| Option | Description | Default |
|---|---|---|
-d, --dir |
Save directory | . |
-o, --out |
Output filename | auto |
-s, --split |
Connections per server | 1 |
-x, --max-connection-per-server |
Max connections per server | 1 |
--max-download-limit |
Max download speed | unlimited |
--timeout |
Timeout in seconds | 60 |
-q, --quiet |
Quiet mode | false |
BitTorrent Download
URI List File
Create a text file with URIs (one entry per block, Tab-separated mirrors):
dir=/downloads
split=5
http://mirror1.example.com/file.iso http://mirror2.example.com/file.iso
http://mirror3.example.com/file.iso
Then:
Architecture
The workspace contains four Rust crates plus Python and Node.js bindings. Test status is reported from reproducible commands in docs/compatibility-status.md, rather than as a fixed historical test count.
Verification snapshot (2026-08-08): the protocol, RPC, and CLI crates pass
their all-feature package test suites; the core all-feature targets executed
3,411 passing tests with 11 ignored and 0 failures before a Windows build
timeout while the final target was starting. Node.js binding tests pass 123/123
and Python binding tests pass 137/137 with a real aria2c binary. The single
workspace aggregate command is still a build-time timeout on this host, so
these results do not mean the migration is complete.
The project is organized as a Cargo workspace with 4 crates:
aria2-rust/
├── aria2/ # Binary crate (CLI entry point, ~550 lines)
│ ├── src/main.rs # Entry point
│ ├── src/app.rs # App runtime (ConfigManager + Engine)
│ └── examples/ # Usage examples
├── aria2-core/ # Core library (~7,000 lines)
│ ├── src/engine/ # Download engine (12 command implementations)
│ │ ├── download_engine.rs # Event loop with command queue
│ │ ├── download_command.rs # HTTP/HTTPS downloader
│ │ ├── ftp_download_command.rs # FTP/SFTP downloader
│ │ ├── bt_download_command.rs # BitTorrent downloader
│ │ ├── magnet_download_command.rs # Magnet link downloader
│ │ ├── metalink_download_command.rs # Metalink downloader
│ │ └── concurrent_download_command.rs # Multi-segment downloader
│ ├── src/config/ # Configuration system (~95 options)
│ │ ├── option.rs # OptionType/Value/Def/Registry
│ │ ├── parser.rs # Multi-source parser (CLI/file/env/defaults)
│ │ ├── netrc.rs # NetRC authentication parser
│ │ ├── uri_list.rs # URI list file (-i option) parser
│ │ └── mod.rs # ConfigManager unified runtime manager
│ ├── src/request/ # Request management
│ │ ├── request_group_man.rs # Global task manager
│ │ └── request_group.rs # Per-task state machine
│ ├── src/filesystem/ # Disk I/O
│ │ ├── disk_writer.rs # Disk writer trait
│ │ ├── disk_cache.rs # Cached writer (256KB direct write)
│ │ ├── control_file.rs # .aria2 control file format
│ │ ├── file_allocation.rs # Pre-allocation strategies
│ │ └── checksum.rs # Checksum verification
│ ├── src/http/ # Cookie management
│ │ ├── cookie.rs # Cookie structure
│ │ ├── cookie_storage.rs # Persistent storage
│ │ └── ns_cookie_parser.rs # Netscape format parser
│ ├── src/session/ # Session persistence
│ │ ├── session_serializer.rs # Serialization
│ │ ├── auto_save_session.rs # Auto-save
│ │ └── save_session_command.rs # Save on exit
│ ├── src/rate_limiter.rs # Token bucket rate limiting
│ └── src/ui.rs # Progress bar & status panel
├── aria2-protocol/ # Protocol stack (~5,000 lines)
│ ├── src/http/ # HTTP/HTTPS client (auth/proxy/cookies/compression)
│ ├── src/ftp/ # FTP/SFTP client (anonymous+auth, passive mode)
│ ├── src/bittorrent/ # Full BT stack
│ │ ├── bencode/ # BEP3 bencode codec
│ │ ├── torrent/ # .torrent parsing
│ │ ├── magnet.rs # Magnet link parsing
│ │ ├── dht/ # KRPC + routing table + bootstrap
│ │ ├── tracker/ # UDP/HTTP tracker
│ │ ├── peer/ # Peer connection + handshake
│ │ ├── extension/ # MSE/PEX/ut_metadata
│ │ └── piece/ # Piece manager + picker
│ └── src/metalink/ # Metalink V3/V4 parser
├── aria2-rpc/ # RPC server (~1,000 lines)
│ ├── src/json_rpc.rs # JSON-RPC 2.0 codec
│ ├── src/xml_rpc.rs # XML-RPC codec
│ ├── src/websocket.rs # WebSocket event publisher
│ ├── src/server.rs # HTTP server (auth/CORS/status)
│ └── src/engine.rs # RpcEngine bridge (25 RPC methods)
└── bindings/ # Language bindings (~1,200 lines)
├── python/ # Python SDK (~600 lines)
└── nodejs/ # Node.js SDK (~627 lines TS)
└── Cargo.toml # Workspace configuration
Library Usage
As a library in your Rust project
Add to your Cargo.toml:
[]
= { = "../aria2-core" }
= { = "../aria2-rpc" }
Minimal download example
use ConfigManager;
use RequestGroupMan;
use DownloadOptions;
use OptionValue;
async
RPC server example
use RpcEngine;
use JsonRpcRequest;
async
Building from Source
Requirements
- Rust: 1.70 or later (install)
- OS: Windows 10+, macOS 10.15+, Linux (glibc 2.17+)
Build Commands
# Debug build (fast compilation)
# Release build (optimized)
# Run tests
# Generate documentation
# Run a specific example
Testing
Running Tests
# Run all tests in workspace
# Run tests for specific crate
# Run tests with verbose output
# Run specific test category
Test Categories
| Category | Prefix | Description |
|---|---|---|
| Unit Tests | test_ |
Inline tests for individual functions |
| Integration Tests | test_ |
Module interaction tests |
| E2E Tests | test_e2e_ |
Complete workflow tests |
| Stress Tests | test_stress_ |
High-load stability tests |
| Edge Case Tests | test_edge_ |
Boundary condition tests |
| Error Path Tests | test_error_ |
Error handling tests |
Coverage Report
# Install cargo-tarpaulin (Linux/macOS)
# Generate HTML coverage report
# Generate LCOV format for CI
Running Benchmarks
# Run all benchmarks
# Run specific benchmark
For comprehensive testing guidance, see docs/testing-guide.md.
Compatibility with Original aria2
The table below records implemented code paths, not full compatibility. The
authoritative status is the module matrix in
docs/compatibility-status.md; an implemented
path can still be PARTIAL or UNVERIFIED there.
| Feature | Path state | Notes |
|---|---|---|
| CLI arguments | Implemented path | ~50 most-used options; full option parity is still open |
Configuration file (aria2.conf) |
Implemented path | Same syntax path; defaults and changeability still need comparison |
| Environment variables | Implemented path | ARIA2_* prefix mapping; full parity is still open |
| JSON-RPC API | Implemented path | 36 all-features methods returned by system.listMethods; interoperability remains open |
| XML-RPC API | Implemented path | MethodCall/response/fault paths exist; original-client matrix remains open |
| WebSocket events | Implemented path | 6 notifications returned by system.listNotifications |
URI list file (-i) |
Implemented path | Mirror + inline options |
| NetRC auth | Implemented path | machine/default/macdef parsing |
| Session save/load | Implemented path | Round-trip tests exist; complete control-file parity remains open |
| Metalink V3/V4 | Implemented path | Parsing and downloads exist; torrent metaurl lifecycle is partial |
| BitTorrent DHT | Implemented path | KRPC + routing table + bootstrap; live interoperability remains open |
| FTP/SFTP | Implemented path | Passive mode + auth; live-server evidence remains open |
| Rate limiting | Implemented path | Shared token bucket and runtime updates are tested |
| Cookie management | Implemented path | Netscape and SQLite parsing paths exist |
| MSE/PE encryption | Implemented path | BEP14 handshake |
| Magnet link support | Implemented path | ut_metadata fetching |
| RarestFirst piece | Implemented path | Piece selection implementation and tests |
| Endgame mode | Implemented path | Last-piece optimization |
| DHT persistence | Implemented path | dht.dat serialization |
| uTP Protocol | Extension path | Not in original aria2 C++ |
| Web Seeds | Implemented path | BEP 19 |
| LPD | Implemented path | Local Peer Discovery |
| Seeding Mode | Implemented path | Upload support |
Known gaps and verification status:
- This table is a capability inventory, not a release compatibility claim.
- The migration is not currently all pass; optional features, ignored network tests, binding E2E suites, and the public C ABI remain tracked work.
aria2.forceShutdown,system.listMethods, andsystem.listNotificationsare implemented and covered by handler/integration tests.- HTTPS RPC has TLS configuration, server implementation, and dedicated test coverage; broader client/server interoperability testing remains tracked.
- IPv6 DHT has CLI and protocol support; full network interoperability coverage remains tracked.
- Additional CLI/runtime option behavior still requires systematic comparison against
aria2_original.
License
This project is licensed under GPL-2.0-or-later, consistent with the original aria2 project.
Copyright (C) 2024 aria2-rust contributors.