Maintained aria2 fork with extensive bug fixes and modernized architecture.
[](https://github.com/AnInsomniacy/aria2-next/actions/workflows/ci.yml)
[](https://github.com/AnInsomniacy/aria2-next/releases)
[](COPYING)
## Why Aria2 Next?
aria2 is remarkable open source software. For over a decade it has been one of the most capable download engines available, trusted by countless tools and users worldwide. We are deeply grateful to the original authors and contributors of the [aria2 project](https://github.com/aria2/aria2). They built something that has stood the test of time, and that enduring quality is the best testament to their vision and craftsmanship.
But upstream development has slowed dramatically in recent years. Dependencies grew stale, builds broke on modern platforms, and a backlog of bugs went unaddressed. We picked up the baton: migrated the codebase to a modern build framework, triaged and fixed a substantial number of upstream issues, and introduced ED2K protocol support for the first time. A full audit trail is preserved in [`docs/maintenance/upstream-issue-review/matrix.csv`](docs/maintenance/upstream-issue-review/matrix.csv).
Aria2 Next is an actively maintained download engine and the embedded engine used by [Rayburst](https://github.com/AnInsomniacy/rayburst). HTTP, HTTPS, SFTP, Metalink, ED2K, RPC, and libaria2 remain supported. HTTP, HTTPS, SFTP, and Metalink payload transfers use libcurl 8.21 with nghttp2. BitTorrent uses libtorrent-rasterbar 2.1. FTP and the former custom stream protocol stacks have been removed.
Stream, BitTorrent, and ED2K resume state is stored under `--state-dir`. Payload directories no longer receive adjacent `.aria2` control files. HTTP cookies, authentication, proxies, TLS, SFTP, resume validation, and HTTP/2 use their native library implementations. HTTP and HTTPS transfers use libcurl's event-driven multi-socket API, adaptive verified byte ranges, HTTP/2 multiplexing, shared cookies and TLS sessions, and range-aware SQLite resume state.
Automatic stream filenames decode the URL basename once using libcurl. Explicit
`--out` values and metadata-defined paths remain literal; request URLs are unchanged.
HTTP range transfers retain unreturned portions of valid partial responses and
retry only unfinished data. Connection setup and low-speed timeouts use libcurl;
server overload reduces new request concurrency and staggers retries. Slow tail
ranges are split only when the remaining work justifies another request. Paused
stream tasks restore their saved progress before resuming network activity.
HTTP 403 does not lower the concurrency budget. HTTP 429/503 reduces it once
per request generation; subsequent payload progress restores concurrency
without waiting for an entire range to complete.
Validated redirect destinations are reused for subsequent ranges. Expired
destinations are refreshed through one request per source route instead of sending
every range back through a signed entry point. Credentials retain their
original origin boundary, and cookies remain managed by libcurl.
Unrestricted parallel HTTP downloads use a bounded set of workers across
available address families. Workers retain their transport choice while taking
ranges from one queue; faster workers complete more work without changing the
path of other active transfers. Redirect destinations belong to their source
route. Received bytes stay committed to the same range planner, and idle workers
can assist unfinished ranges. DNS, connection establishment, TLS, and pooling
remain native libcurl operations. Explicit IPv4, interface, proxy, and rate-limit
settings are respected.
Magnet downloads keep one GID from metadata discovery through file selection, payload transfer, and seeding. With `pause-metadata=true`, the same GID remains paused with a complete file list and `bittorrent.fileSelectionState=awaiting` until a valid `select-file` is submitted. Aria2 Next then replaces the metadata-only native handle with a checked libtorrent handle that already contains the final file priorities. This prevents stale partfiles from entering the payload session.
The BitTorrent session persists native IPv4 and IPv6 DHT routing state, restores paused torrents into libtorrent without activating network transfer, checkpoints fast-resume data while running, preserves representable tracker tiers, compacts only excess lowest-priority tiers, and isolates private torrents from global tracker injection. Paused tasks retain verified task and file progress across process restarts. Permanent task removal deletes fast-resume and partfile state as one native operation. TCP, uTP, PEX, Local Peer Discovery, UPnP/NAT-PMP, transport encryption, v1/v2 torrents, sparse or allocated storage, sequential mode, and HTTP/SOCKS proxying use native libtorrent facilities.
Advanced native controls cover request and disk queues, disk I/O policy, peer turnover, TCP/uTP balancing, upload scheduling, file priorities, web seeds, manual peers, and resume checkpoints. Runtime diagnostics report peer discovery, tracker, DHT, transport, disk queue, protocol overhead, and aggregated performance-warning state through JSON-RPC.
## Native HLS and DASH Downloads
HLS (`.m3u8`) and MPEG-DASH (`.mpd`) use native GPAC, libcurl, and FFmpeg
libraries inside the same engine. Media tasks support representation selection,
live recording, paused restart, and MP4/Matroska output without transcoding.
Media progress uses presentation duration rather than an invented output size.
See [media downloads](docs/media-downloads.md) for CLI/RPC contracts and scope.
## Native ED2K/eMule Support
Aria2 Next includes native ED2K/eMule support aligned with aMule's network behavior. ED2K works through the normal aria2 CLI, session, and JSON-RPC flows, including server and Kad discovery, peer transfer, search, sharing, upload queues, protocol obfuscation, persistent runtime identity, and restart source seeds. The maintained architecture and verification scope are documented in [`docs/maintenance/ed2k-runtime.md`](docs/maintenance/ed2k-runtime.md).
## Compatibility
| Surface | Current contract |
| --- | --- |
| Executable | `aria2-next` |
| CLI | Maintained aria2-next options with retired aria2 input normalization |
| Configuration | aria2 key-value format with retired input normalization |
| Sessions | Canonical aria2-next task files and native engine resume data |
| RPC | Maintained aria2 JSON-RPC methods, retired option normalization, and native extensions |
| Library | Public libaria2 headers with retired option normalization |
Rayburst embeds this engine, and release artifacts are standalone binaries.
Linux release binaries require glibc 2.35 or newer and a compatible system C++
runtime, matching the Ubuntu 22.04 build and container baseline.
Recognized retired aria2 options are mapped when a current equivalent exists or
skipped with one warning when the native engine owns or removed the behavior.
Unknown option names remain errors. Legacy task state and adjacent `.aria2`
control files are not imported.
`always-resume` is accepted as a retired boolean option, including the
`--always-resume=false` argument supplied by yt-dlp. It is skipped with a warning;
native recovery ownership, bounded full-response restarts and explicit overwrite
settings determine the download behavior.
## Quick Start
Download a file:
```bash
aria2-next https://example.com/file.iso
```
Download an ED2K file link:
```bash
aria2-next '