aria2-next keeps the aria2 interface and swaps the engine underneath

Why a new engine when the old one still runs

The stated motivation is specific rather than ideological. The project describes aria2 as remarkable open source software and thanks its authors and contributors, then explains the problem plainly: upstream development has slowed, its dependencies have aged, and many of its bugs stayed open. That combination, an interface people depend on paired with a codebase nobody is moving forward, is the classic trigger for a rewrite. Aria2 Next keeps what users and frontends rely on and replaces the engine behind them. What that means for a user is unusually low friction: the command line, configuration files, session files, JSON-RPC and XML-RPC all stay, so a script or a frontend that drives aria2 has a good chance of working unchanged against aria2-next. The trade-off is that the binary is named aria2-next, and everything that hardcodes the name aria2 has to be adjusted. The engine is also embedded in Rayburst, which is the author's own frontend, and that is worth knowing because it means the RPC surface is shaped partly by internal needs rather than only by legacy compatibility.

Each protocol is delegated to a library that owns it

The architecture is best described as an ownership map. libcurl handles HTTP(S) and SFTP, with SFTP going through libssh2. libtorrent-rasterbar 2.1 handles BitTorrent and magnet links, covering DHT, PEX, LSD, uTP, encryption, v1 and v2, UPnP and NAT-PMP, and file selection before download. GPAC and FFmpeg handle HLS and DASH, including track selection, live recording, restartable segments and MP4 or Matroska output without transcoding. SQLite holds state, and Boost.Asio, Beast and JSON provide the event loop and the RPC layer. Metalink version 4 is supported per RFC 5854. ED2K and Kad are the exception, implemented natively in the project's own code and checked on the wire against aMule, covering server and Kad sources and search, hash sets, compressed and obfuscated transfers, upload queue and credits, and UPnP port mapping. The project's own code is described as limited to what no library provides: segment scheduling, the task queue, ED2K and Kad, and the aria2-compatible surface. That is a defensible boundary, and it means most of the maintenance burden of a download engine is delegated rather than carried.

The HTTP path is where the interesting engineering lives

Within the HTTP implementation the documentation lists behaviours that go beyond a plain download. Byte ranges are adaptive and split by measured speed, so a slow tail is broken into pieces rather than fetched as one long transfer. Slow tails are raced in an endgame phase. Retries honour a Retry-After header from the server. Resumption is validated with a strong ETag or with a Last-Modified that is at least 60 seconds older than the server's Date, which is a deliberate rejection of weak resume evidence since resuming onto changed content is how you end up with a corrupt file that looks complete. Two of the recent release notes point the same way. v3.0.6 is titled Fair Connection Sharing and Implied Ranges, and v3.0.7 is titled Intact Files, UTF-8 Torrent Names and Clear Drive Errors, which reads like a set of correctness fixes around file integrity, name handling and error messages. The project also ships tooling that checks this behaviour rather than asserting it: tools/transfer_validation exercises HTTP against fault-injecting servers, SFTP, BitTorrent, ED2K, Metalink and HLS/DASH end to end, and tools/bench measures throughput, tail latency, CPU and memory under throttling, stalls, resets, overload and broken ranges.

The compatibility table is the contract, and it has holes

This is the section to read before planning a migration. The executable is aria2-next, not aria2. Command line options follow aria2, but retired options are mapped to their replacement or skipped with a single warning, and unknown options are errors. Configuration keeps the aria2 key=value format, and session files keep the aria2 input-file format. RPC covers aria2 JSON-RPC over HTTP and WebSocket, aria2 XML-RPC over HTTP at /rpc, system.multicall, notifications, a token secret, plus extensions for ED2K, BitTorrent and media. Then there is the list of what is not provided: FTP, Metalink 3, JSONP and the libaria2 C++ library. Two of those omissions can bite. FTP being absent removes a transport that some download scripts still use, and the libaria2 C++ library being absent means a program that linked against aria2's own C++ API has no direct replacement here. The examples directory does contain libaria2ex.cc and libaria2wx.cc files, so the shape of that API is still visible in the tree even though the library itself is not shipped. The state story is different too. Task state of the original aria2, meaning the .aria2 control files, is not imported, and progress lives under --state-dir instead of in .aria2 files next to the payload. A task resumes after a crash from its last checkpoint, set with --state-save-interval, and a paused task shows its stored progress after a restart. Migrating means losing in-flight state, not configuration.

Building it means compiling every dependency yourself

The build story is a superbuild that compiles all library dependencies from third_party/ without network access, which is a deliberate choice for reproducible and auditable builds. The requirements are CMake 3.25 or newer, Ninja, a POSIX shell, Make, Perl and a C11 and C++20 toolchain, with MSYS2 supplying the shell, Make and Perl on Windows while compilation uses the native target toolchain. The build commands are short:

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

Three build options exist: ARIA2_ENABLE_WERROR, ARIA2_RELEASE_SIZE_OPTIMIZED and ARIA2_RELEASE_LTO, and tools/build_test.sh builds and tests each of them. Prebuilt artifacts are published on the releases page for Linux x86_64 and ARM64, macOS on Apple Silicon and Intel, Windows on x86_64 and ARM64, and Android 7.0 or later on ARM64, with a checksums file per release. Linux binaries need glibc 2.35 or newer, and if the executable bit was cleared on a Linux, macOS or Android download, the fix is chmod +x on the file. Container images for Linux x86_64 and ARM64 go to the GitHub Container Registry, and the compose file lives at packaging/docker/compose.yml, with an environment where PUID and PGID are set to your own ids so the mounted volumes stay writable. The entrypoint assigns the writable mounts to those ids and creates the configuration and session files when they are absent.

RPC exposure is the operational risk to plan for

Running the engine as a service is the mode that most deployments end up in, and the documentation is specific about the security consequence. The quick start includes starting the engine with RPC enabled on a port, and the container example publishes that port. The advice is to add --rpc-secret=<token> before exposing RPC beyond a trusted network, which is the same rule that applies to any JSON-RPC interface with a multicall method. The compose example publishes port 6800, mounts a downloads directory, a config directory and a state directory, and sets PUID and PGID so the container does not write as root into your working directory. Certificate handling is delegated to libcurl and follows the platform convention: Schannel and the system store on Windows, SecTrust on macOS, and the OpenSSL default paths on Linux and Android while honouring SSL_CERT_FILE and SSL_CERT_DIR, with --ca-certificate available to name a CA file explicitly. For a self-hosted deployment, the combination to plan for is a bound port, an rpc secret, and a state directory on durable storage, because that directory is where a paused task's progress lives.

Licence, versioning, and how fast this is moving

The project is GPL-2.0, with the licence text in COPYING, and that is a meaningful difference from upstream aria2 for anyone embedding it in a product, since GPL-2.0 carries copyleft obligations that a permissive licence would not. The project is under active development by any reasonable reading: the last push to the repository was on 2026-10-20, and the release history shows three releases in four days, v3.0.6 on 2026-10-17, v3.0.7 on 2026-10-19 and v3.0.8 on 2026-10-20, the last of which is titled Restored 2.8 RPC Methods, implying the previous release broke something that older clients relied on. That pace is both a strength and a risk. A rapid release cadence means fixes arrive quickly, and it also means a client can break between versions, as the 2.8 RPC restoration shows. The versioning itself is disciplined: CMakeLists.txt is the project version source of truth, release tags use the form v{PROJECT_VERSION}, and 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. The repository also carries an AGENTS.md, an AUTHORS file, .clang-format, CMakePresets.json and a docs/ directory with architecture, media download and contribution guides.

Editorial conclusion

Adopt aria2-next if you already run aria2 and want the same command line, configuration and RPC contract on a codebase that is still moving, or if you build a frontend that speaks aria2 RPC and want the protocol work done for you. Do not adopt it if you depend on FTP, Metalink 3, JSONP, the libaria2 C++ library, or on importing old .aria2 control files, because none of those are provided. Before switching, read the compatibility table rather than assuming parity, check that your frontends tolerate the renamed aria2-next executable and the recent changes to the 2.8 RPC methods, and confirm your Linux hosts meet the glibc 2.35 floor.

Frequently asked questions

Official sources

1. AnInsomniacy/aria2-next on GitHub
2. Issues
3. License: GPL-2.0
4. README
5. Releases