<!-- IMPORTANT: This file is generated from the template at 'scripts/templates/README.md'. Please update the template instead of this file. -->

aria2p

Command-line tool and Python library to interact with an aria2c daemon process through JSON-RPC.

To avoid confusion:

• aria2 is a lightweight multi-protocol & 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. It can act as a daemon.
• aria2p (p for Python) is a command-line client that can interact with an aria2c daemon. It is not an official client. There are other Python packages allowing you to interact with an aria2c daemon. These other packages do not offer enough usability (in my opinion), this is why I'm developing aria2p.

Purpose: aria2c can run in the foreground, for one-time downloads, or in the background, as a daemon. This is where aria2p intervenes: when an instance of aria2c is running in the background, aria2p will be able to communicate with it to add downloads to the queue, remove, pause or resume them, etc.

In order for aria2p to be able to communicate with the aria2c process, RPC mode must be enabled with the --enable-rpc option of aria2c. RPC stands for Remote Procedure Call. Although aria2c supports both JSON-RPC and XML-RPC protocols, aria2p works with JSON only (not XML). More information about how to configure aria2c to run as a daemon with RPC mode enabled can be found in the Configuration section of the documentation.

Table of contents

• Requirements
• Installation
• Usage as a library
• Usage on the command line
• Troubleshoot
• Support

Requirements

aria2 must be installed. On systems with apt-get:

sudo apt-get install aria2

aria2 is also available on conda-forge:

conda install -c conda-forge aria2

Installation

python3.6 -m pip install aria2p[tui]

With uv:

uv tool install aria2p[tui]

The tui extra is needed for the interactive interface. If you don't need the interface (for example when you are writing a Python package with a dependency to aria2p), simply install aria2p without any extra.

Usage (as a library)

This library is still a work in progress. More examples will be added later. In the meantime, you can read the Reference section on the official documentation.

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)

Usage (command-line)

usage: aria2p [GLOBAL_OPTS...] COMMAND [COMMAND_OPTS...]

Command-line tool and Python library to interact with an `aria2c` daemon
process through JSON-RPC.

Global options:
  -h, --help            Show this help message and exit. Commands also accept
                        the -h/--help option.
  -p PORT, --port PORT  Port to use to connect to the remote server.
  -H HOST, --host HOST  Host address for the remote server.
  -s SECRET, --secret SECRET
                        Secret token to use to connect to the remote server.
  -L {TRACE,DEBUG,INFO,SUCCESS,WARNING,ERROR,CRITICAL}, --log-level {TRACE,DEBUG,INFO,SUCCESS,WARNING,ERROR,CRITICAL}
                        Log level to use
  -P LOG_PATH, --log-path LOG_PATH
                        Log path to use. Can be a directory or a file.
  -T CLIENT_TIMEOUT, --client-timeout CLIENT_TIMEOUT
                        Timeout in seconds for requests to the remote server.
                        Floats supported. Default: 60.0.

Commands:
  
    add                 Add downloads with URIs/Magnets/torrents/Metalinks.
    add-magnets (add-magnet)
                        Add downloads with Magnet URIs.
    add-metalinks (add-metalink)
                        Add downloads with Metalink files.
    add-torrents (add-torrent)
                        Add downloads with torrent files.
    autopurge (autoclear)
                        Automatically purge completed/removed/failed
                        downloads.
    call                Call a remote method through the JSON-RPC client.
    pause (stop)        Pause downloads.
    remove (rm, del, delete)
                        Remove downloads.
    resume (start)      Resume downloads.
    show                Show the download progression.
    top                 Launch the top-like interactive interface.
    listen              Listen to notifications.

Calling aria2p without any arguments will by default call the top command, which is a console interactive interface.

Commands:

• add
• add-magnets
• add-metalinks
• add-torrents
• autopurge
• call
• listen
• pause
• remove
• resume
• show
• top

---

add

usage: aria2p add [-h] [-f FROM_FILE] [uris [uris ...]]

Add downloads with URIs/Magnets/torrents/Metalinks.

positional arguments:
  uris                  The URIs/file-paths to add.

optional arguments:
  -h, --help            Show this help message and exit.
  -f FROM_FILE, --from-file FROM_FILE
                        Load URIs from a file.

---

add-magnets

usage: aria2p add-magnets [-h] [-f FROM_FILE] [uris [uris ...]]

Add downloads with Magnet URIs.

positional arguments:
  uris                  The magnet URIs to add.

optional arguments:
  -h, --help            Show this help message and exit.
  -f FROM_FILE, --from-file FROM_FILE
                        Load URIs from a file.

---

add-metalinks

usage: aria2p add-metalinks [-h] [-f FROM_FILE]
                            [metalink_files [metalink_files ...]]

Add downloads with Metalink files.

positional arguments:
  metalink_files        The paths to the metalink files.

optional arguments:
  -h, --help            Show this help message and exit.
  -f FROM_FILE, --from-file FROM_FILE
                        Load file paths from a file.

---

add-torrents

usage: aria2p add-torrents [-h] [-f FROM_FILE]
                           [torrent_files [torrent_files ...]]

Add downloads with torrent files.

positional arguments:
  torrent_files         The paths to the torrent files.

optional arguments:
  -h, --help            Show this help message and exit.
  -f FROM_FILE, --from-file FROM_FILE
                        Load file paths from a file.

---

autopurge

usage: aria2p autopurge [-h]

Automatically purge completed/removed/failed downloads.

optional arguments:
  -h, --help  Show this help message and exit.

---

call

usage: aria2p call [-h] [-P PARAMS [PARAMS ...] | -J PARAMS] method

Call a remote method through the JSON-RPC client.

positional arguments:
  method                The method to call (case insensitive). Dashes and
                        underscores will be removed so you can use as many as
                        you want, or none. Prefixes like 'aria2.' or 'system.'
                        are also optional.

optional arguments:
  -h, --help            Show this help message and exit.
  -P PARAMS [PARAMS ...], --params-list PARAMS [PARAMS ...]
                        Parameters as a list of strings.
  -J PARAMS, --json-params PARAMS
                        Parameters as a JSON string. You should always wrap it
                        at least once in an array '[]'.

As explained in the help text, the method can be the exact method name, or just the name without the prefix. It is case-insensitive, and dashes and underscores will be removed.

The following are all equivalent:

• aria2.addUri
• aria2.adduri
• addUri
• ADDURI
• aria2.ADD-URI
• add_uri
• A-d_D-u_R-i (yes it's valid)
• A---R---I---A---2.a__d__d__u__r__i (I think you got it)
• and even more ugly forms...

Examples

List all available methods. This example uses jq.

$ aria2p call listmethods | jq
[
  "aria2.addUri",
  "aria2.addTorrent",
  "aria2.getPeers",
  "aria2.addMetalink",
  "aria2.remove",
  "aria2.pause",
  "aria2.forcePause",
  "aria2.pauseAll",
  "aria2.forcePauseAll",
  "aria2.unpause",
  "aria2.unpauseAll",
  "aria2.forceRemove",
  "aria2.changePosition",
  "aria2.tellStatus",
  "aria2.getUris",
  "aria2.getFiles",
  "aria2.getServers",
  "aria2.tellActive",
  "aria2.tellWaiting",
  "aria2.tellStopped",
  "aria2.getOption",
  "aria2.changeUri",
  "aria2.changeOption",
  "aria2.getGlobalOption",
  "aria2.changeGlobalOption",
  "aria2.purgeDownloadResult",
  "aria2.removeDownloadResult",
  "aria2.getVersion",
  "aria2.getSes