GitHub - AnInsomniacy/aria2-next: Redefining the next generation of aria2

aria2 is remarkable open source software, and we are grateful to the authors and contributors of the aria2 project. Its upstream development has slowed, its dependencies aged and many of its bugs stayed open.

Aria2 Next keeps what users and frontends rely on — the aria2 command line, configuration files, session files, JSON-RPC and XML-RPC — and replaces the engine behind them. Each protocol is handled by a library that owns it: libcurl for HTTP(S) and SFTP, libtorrent for BitTorrent, GPAC and FFmpeg for HLS/DASH, SQLite for state, Boost.Asio, Beast and JSON for the event loop and RPC. The code of its own is limited to what no library provides: segment scheduling, the task queue, ED2K/Kad, and the aria2-compatible surface. It is the engine embedded in Rayburst.

Protocols

Progress lives under --state-dir, not in .aria2 files next to the payload. A task resumes after a crash from its last checkpoint (--state-save-interval), and a paused task shows its stored progress after a restart.

Compatibility

Not provided: FTP, Metalink 3, JSONP and the libaria2 C++ library. Task state of the original aria2 (.aria2 control files) is not imported.

--always-resume=false, as passed by yt-dlp, is accepted and skipped with a warning.

Quick Start

aria2-next https://example.com/file.iso
aria2-next 'magnet:?xt=urn:btih:...'
aria2-next '<ed2k-file-link>'
aria2-next --enable-rpc --rpc-listen-port=6800
aria2-next --help=#all

Build

cmake --preset default
cmake --build --preset default
ctest --preset default
build/default/aria2-next --version

The default superbuild compiles every library dependency from third_party/ without network access. CMake 3.25+, Ninja, a POSIX shell, Make, Perl and a C11/C++20 toolchain are required; on Windows, MSYS2 supplies the shell, Make and Perl while compilation uses the native target toolchain.

Build options: ARIA2_ENABLE_WERROR, ARIA2_RELEASE_SIZE_OPTIMIZED, ARIA2_RELEASE_LTO. tools/build_test.sh builds and tests each of them.

Transfer behaviour is checked end to end by tools/transfer_validation (HTTP against fault-injecting servers, SFTP, BitTorrent, ED2K, Metalink, HLS/DASH) and tools/bench (throughput, tail latency, CPU and memory under throttling, stalls, resets, overload and broken ranges). Contribution guidelines are in docs/CONTRIBUTING.md.

Downloads

Prebuilt artifacts are published on the GitHub Releases page.

Linux, macOS and Android downloads are executable files; if the executable bit was cleared, run chmod +x ./aria2-next-<version>-<platform>. Linux binaries require glibc 2.35 or newer.

Container images for Linux x86_64 and ARM64 are published to the GitHub Container Registry:

docker run -d --name aria2-next \
  -p 6800:6800 \
  -e PUID="$(id -u)" \
  -e PGID="$(id -g)" \
  -v "$PWD/downloads:/downloads" \
  -v "$PWD/config:/config" \
  -v "$PWD/state:/var/lib/aria2-next" \
  ghcr.io/aninsomniacy/aria2-next:latest

or PUID="$(id -u)" PGID="$(id -g)" docker compose -f packaging/docker/compose.yml up -d. The entrypoint assigns the writable mounts to PUID/PGID and creates the configuration and session files when absent. Add --rpc-secret=<token> before exposing RPC beyond a trusted network.

HTTPS certificates are verified by libcurl: Schannel and the system store on Windows, SecTrust on macOS, OpenSSL default paths (honouring SSL_CERT_FILE and SSL_CERT_DIR) on Linux and Android. --ca-certificate names a CA file explicitly.

Release and Versioning

CMakeLists.txt is the project version source of truth; release tags use v{PROJECT_VERSION}. Publishing a GitHub Release builds all platform binaries, uploads them with SHA-256 checksums, and then publishes the container image for the same tag. Release dependency versions are tracked in packaging/dependencies.env.

Repository Layout

The upstream issue audit is preserved in docs/maintenance/upstream-issue-review/.

License

Same as aria2: GPLv2. The OpenSSL linking exception text is preserved in docs/licenses/OPENSSL.md.