aria2p: a Python client and CLI for driving an aria2c daemon over JSON-RPC

The distinction between aria2, aria2c and aria2p

The readme opens with a disambiguation, which is necessary because the three names are easy to confuse and because aria2p is a third-party tool rather than part of aria2 itself.

aria2 is a lightweight multi-protocol and multi-source, cross platform download utility operated in command-line. It supports HTTP/HTTPS, FTP, SFTP, BitTorrent and Metalink.

aria2c is the name of the command-line executable provided by aria2, and it can act as a daemon.

aria2p, with the p for Python, is a command-line client that can interact with an aria2c daemon. It is not an official client. The readme is direct that other Python packages allow you to interact with an aria2c daemon and that those packages do not offer enough usability, in the author's opinion, which is why aria2p is being developed.

The operational split is what matters in practice. aria2c can run in the foreground for one-time downloads, or in the background as a daemon. When it is running in the background, aria2p can communicate with it to add downloads to the queue, remove, pause or resume them.

The mechanism is JSON-RPC, and there is a constraint attached to it. RPC mode must be enabled with the --enable-rpc option of aria2c. Although aria2c supports both JSON-RPC and XML-RPC protocols, aria2p works with JSON only and not XML. The documentation site has a Configuration section covering how to configure aria2c to run as a daemon with RPC mode enabled.

So the division of labour is: aria2c does the downloading, aria2p manages the queue. That means aria2p is only useful once you already have a daemon, and configuring the daemon is a precondition rather than part of this tool.

Installing aria2c and aria2p, and the tui extra

aria2 itself has to be installed separately, and the readme gives two routes.

sudo apt-get install aria2

conda install -c conda-forge aria2

The conda-forge route matters more than it looks, because it gives you a self-contained environment for the daemon, which is the arrangement that makes the rest of the project practical.

Installing aria2p itself is a single pip command, and the readme shows the plain pip form and the uv form.

python3.6 -m pip install aria2p[tui]

uv tool install aria2p[tui]

The tui extra is needed for the interactive interface. If you do not need the interface, for example when you are writing a Python package with a dependency on aria2p, you install aria2p without any extra. That distinction saves a real dependency, because the extra pulls in asciimatics and pyperclip, and the second of those is a clipboard library you would not want in a server-side package.

The project metadata lists the runtime dependencies as loguru for logging, platformdirs for configuration directories, requests for the HTTP transport of the JSON-RPC calls, and websocket-client for the notification stream. The websocket dependency is the interesting one, because it is what makes the listen command possible.

The version scheme is worth noting: the version is dynamic, taken from a scripts.get_version:get_version callable rather than hardcoded, and the project requires Python 3.11 or later with classifiers for 3.11 through 3.15. The recent releases are 0.12.3 and 0.12.2, both on 2026-10-06, and before that 0.12.1 from 2024-12-25.

The console entry point is defined in the project metadata as aria2p pointing at aria2p:main, so the CLI and the library are installed from the same distribution.

The API object, and what the library gives you over the CLI

The library usage example is short enough to take in at a glance.

import aria2p

# initialization, these are the default values
aria2 = aria2p.API(
    aria2p.Client(
        host="http://localhost",
        port=6800,
        secret=""
    )
)

# list downloads
downloads = aria2.get_downloads()

for download in downloads:
    print(download.name, download.download_speed)

# add downloads
magnet_uri = "magnet:?xt=urn:..."

download = aria2.add_magnet(magnet_uri)

The structure is two layers. A Client holds the connection parameters, and an API wraps it with the operations. The default connection is a local daemon on port 6800 with an empty secret, which is the aria2 default RPC port.

The operations map onto what the daemon exposes. get_downloads returns objects with attributes such as name and download_speed, and add_magnet takes a magnet URI and returns a download object. The distinction between add and add_magnet is carried through the whole API, with separate methods for URIs, magnets, torrents and metalinks, matching the command-line split.

The author is upfront about the state of this side of the project. The library is still a work in progress, more examples will be added later, and in the meantime you can read the Reference section on the official documentation. That is a fair warning to take seriously: the library surface is documented on the site rather than in the readme, so the readme example is a starting point rather than a reference.

The empty secret in the example is worth pausing on, because it is where the security question sits. If the daemon is reachable beyond localhost, an empty secret means anyone who can reach the RPC port can add and remove downloads. The CLI exposes the secret as a global option, and the documentation's Configuration section is the place to set it on the daemon side.

The command set, and the two commands that make it a client rather than a wrapper

The global options and the command list are printed by the tool itself, and the shape of it is worth reading because it shows what the author considered worth exposing.

The global options are port, host, secret, log level with the choices TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR and CRITICAL, log path which can be a directory or a file, and a client timeout in seconds with floats supported and a default of 60.0.

The commands are add, add-magnets with the alias add-magnet, add-metalinks, add-torrents, autopurge with the alias autoclear, call, pause with the alias stop, remove with the aliases rm, del and delete, resume with the alias start, show, top and listen.

Two of these do more than wrap a single RPC method. The call command calls a remote method through the JSON-RPC client directly, which is the escape hatch: anything the daemon exposes that aria2p has not wrapped can still be reached. The listen command listens for notifications, which is where the websocket-client dependency earns its place, because aria2 pushes notification messages such as download completion and status changes over the notification channel rather than making the client poll.

The autopurge command automatically purges completed, removed or failed downloads. That is a housekeeping command that exists because the aria2 queue accumulates finished entries, and it is the kind of thing you want on a shared server rather than something you want to do by hand.

The top command launches the top-like interactive interface, and calling aria2p without any arguments calls top by default, so the plain invocation gives you a live view of the daemon's queue rather than a help screen.

The add command takes positional URIs and an optional -f FROM_FILE to load URIs from a file, and the same -f option appears on the magnet and metalink commands. Loading a list from a file is the practical way to queue a batch, and it is the feature that makes the tool usable for a scripted bulk add rather than one URL at a time.

The repository is a template-driven project, and the tooling shows it

The repository layout tells you how the project is developed, and it is unusual in a way that is worth a look.

The readme itself is generated. There is a comment at the top saying the file is generated from a template at scripts/templates/README.md, and that the template should be updated instead of the file. The top-level entries include that scripts/ directory, a .copier-answers.yml file for the Copier template tool, a config/ directory, a duties.py file for the invoke task runner, a zensical.toml for the documentation builder, and a Makefile that exists mainly to hand off to a Python script.

The Makefile makes that explicit. If you have direnv loaded in your shell, and allow it in the repository, the make command will point at the scripts/make shell script. This Makefile is just here to allow auto-completion in the terminal. Its default goal is help, which echoes a message telling you to run direnv allow, or to use python scripts/make ARGS to run the commands or tasks directly.

The action list shows what the project tooling covers: allrun, changelog, check, check-api, check-docs, check-quality, check-security, check-types, clean, coverage, docs, docs-deploy, format, help, multirun, release, run, setup, test and vscode. The per-area check targets are the interesting part, because a separate check-api and check-types alongside check-docs and check-security means the project treats the public API surface and the documentation as things with their own checks rather than a single lint pass.

The docs are built with zensical, and the project metadata points at a documentation URL, a changelog URL, an issues URL and a discussions URL, plus a Gitter room. There is an AI_POLICY.md at the top level next to CODE_OF_CONDUCT.md, CONTRIBUTING.md and CHANGELOG.md, and the licence is ISC with the license-files entry pointing at the LICENSE file.

The last push was on 2026-10-12, two days after the 0.12.3 and 0.12.2 releases went out on the same day, so the project is actively worked on.

What aria2p is not, and how a raw JSON-RPC client compares

Two boundaries are worth naming.

The first is the protocol. aria2p works with JSON only, not XML. If your aria2c is configured to serve XML-RPC, this client cannot talk to it. The readme states this without apology, and it is a deliberate narrowing, but it does mean the tool is not usable against every daemon configuration.

The second is that aria2p is a queue manager, not a downloader. It does not fetch anything itself. Every operation is a request to a daemon that is already running, which means there is a whole class of problem the tool does not touch: starting the daemon, supervising it, keeping it alive across reboots, and scheduling it. For a home machine where you run aria2c in the foreground, that is irrelevant. For a server with a dozen users, the daemon lifecycle is half the work and aria2p does none of it.

The alternative is to talk to the daemon yourself. The JSON-RPC interface is a documented HTTP endpoint, so a script using requests can call the same methods without a dependency, and that is the right choice for a single add in a cron job. What you give up is the typed layer over the RPC responses, the download objects with attributes like name and download_speed, the notification stream over websockets, and the interactive top-like view. What aria2p adds over a raw client is a shape, and the readme's own claim is that the alternatives did not offer enough usability, which is a matter of taste the author has made explicit.

A third option is a different client entirely. Other Python packages exist for the same purpose, and the readme dismisses them on usability grounds without naming them. There are also non-Python options: the aria2c command-line itself has a remote mode, and there are web interfaces built around the RPC server. For a single-user home setup, aria2c's own client is often enough, and for a shared server a web interface may suit an audience that does not want a terminal.

The honest summary is that aria2p is for the case where you want to manage a daemon from Python or from a terminal, and you have decided the JSON-RPC protocol and the client style are what you want. It is not trying to be an aria2 replacement.

Editorial conclusion

aria2p fits a Python developer who already runs aria2c as a daemon and wants to script against it, or a user who wants a top-like view of a shared download server, and it does not fit a project that needs XML-RPC, torrent metadata editing or a Web UI, since the client is JSON-RPC only and the interactive interface is a terminal application. Before using it, enable RPC mode on the daemon with the --enable-rpc option of aria2c and check the secret token setting, because aria2p connects with a host, port and secret and will not reach a daemon that was started without RPC mode.

Frequently asked questions

Official sources

1. License: ISC
2. pawamoy/aria2p on GitHub
3. Project website
4. README
5. Releases