How to download from multiple sources with aria2?

aria2 can pull a single file from multiple parallel sources simultaneously. Use: aria2c -x 16 -s 16 http://mirror1.example.com/file.iso http://mirror2.example.com/file.iso. aria2 will download chunks from both URLs at the same time.

What is the aria2 JSON-RPC API and how do I use it?

aria2's JSON-RPC API is an HTTP server running on port 6800 that lets you add, pause, resume, and monitor downloads programmatically. Start it with: aria2c --enable-rpc --rpc-listen-all --rpc-secret=TOKEN. Then call methods like aria2.addUri via curl or any HTTP client.

How do I configure aria2 to save-session and resume after reboot?

Add to aria2.conf: save-session=~/.aria2/aria2.session and input-file=~/.aria2/aria2.session and save-session-interval=60. aria2 will periodically save all active downloads to the session file and automatically load them on next start.

What does file-allocation=falloc do in aria2?

The falloc mode tells the OS kernel to pre-allocate disk space for the entire file before downloading begins. This prevents filesystem fragmentation during parallel chunk downloads, which is critical for performance on HDDs and NVMe drives when downloading large files (50GB+).

文档 / 安装与基础 / 构建与安装

aria2 文档：安装、配置与自动化

Q: How to build aria2 from source on Linux?

Install dependencies with: sudo apt install libgnutls28-dev nettle-dev libgmp-dev libssh2-1-dev libc-ares-dev libxml2-dev zlib1g-dev libsqlite3-dev pkg-config. Then run: git clone https://github.com/aria2/aria2.git && cd aria2 && autoreconf -i && ./configure && make

aria2 是一款免费、开源的多协议命令行下载工具，采用 C++ 编写，支持 HTTP、HTTPS、FTP、SFTP、BitTorrent 和 Metalink。它可同时建立多达 16 个并行连接，在限制单连接速度的服务器上通常比 wget 或 curl 快数倍，而内存占用仅为 4–9 MiB。适用于 Windows、macOS、Linux 和 Android，无需图形界面。

通过本文档，您可以掌握在 Windows、Linux 和 macOS 上的安装方法，配置高级协议引擎，并将 aria2 集成到自己的自动化流程中。

bash

# 1. Install dependencies (Debian/Ubuntu) $sudo apt install libgnutls28-dev nettle-dev libgmp-dev libssh2-1-dev libc-ares-dev libxml2-dev zlib1g-dev libsqlite3-dev pkg-config # 2. Clone and Build $git clone https://github.com/aria2/aria2.git $cd aria2 $autoreconf -i $./configure $make # OPTIONAL: Build a single static binary for portability $./configure ARIA2_STATIC=yes

交叉编译：aria2 提供了 mingw-config 和 android-config 封装脚本，可分别借助 MinGW 和 NDK 工具链生成 Windows（.exe）和 Android 二进制文件。

文档 / 安装与基础 / HTTP 与 FTP 配置

HTTP 与 FTP 基础配置

aria2 开箱即用即可出色地处理常规 HTTP/FTP 下载，但其真正的强大之处在于 协议混合。它可以同时通过 HTTP/FTP/SFTP 和 BitTorrent 下载同一文件，并将来自直连源的数据上传至 BitTorrent 群组，从而最大化下载效率。

注意：aria2 纯粹是一个命令行程序和 RPC 后端。如果您使用 -x 16 开启 16 个连接，某些服务器可能会暂时限制您的 IP。请务必合理设置并发数。

cli

# Standard execution $aria2c http://example.org/mylinux.iso # Pull from 16 connections simultaneously, splitting the file into 16 chunks $aria2c -x 16 -s 16 http://example.org/mylinux.iso # Parameterized URI: Download file01.iso through file05.iso in one go $aria2c "http://example.org/file{01,02,03,04,05}.iso" # Set custom User-Agent and Referer headers $aria2c --user-agent="MyBrowser/1.0" --referer="http://google.com" http://file.com/d.zip

文档 / 安装与基础 / 快速入门与命令行

批量自动下载

对于网页抓取、镜像同步和批量操作，您可以将包含数千个 URL 的纯文本文件直接交给 aria2。它会使用 -i（输入文件）参数并行高速下载这些链接。

cli

# Read all targets from a formatted text document $aria2c -i huge_list.txt --max-concurrent-downloads=5 # Parameterized bash expansion downloading $aria2c -Z -P "http://host/image[000-100].png"

文档 / 深入解析 / BitTorrent

BitTorrent 深入解析

aria2 核心引擎直接集成了功能完备的 BitTorrent 客户端能力，原生支持 DHT 路由表、本地节点发现（LPD）和磁力链接解析。

注意：aria2 是为数不多的原生支持 BitTorrent WebSeeding 的客户端之一。您可以将标准 HTTP 镜像源同时接入 P2P 群组！

cli

# Download via .torrent file using 55 max peers $aria2c --bt-max-peers=55 ubuntu.torrent # Download via Magnet URI cleanly $aria2c "magnet:?xt=urn:btih:248D0A1CD...&dn=ubuntu" # Stop seeding automatically when ratio hits 1.5 $aria2c --seed-ratio=1.5 ubuntu.torrent

文档 / 深入解析 / Metalink

Metalink 支持

Metalink 是一种包含 URL 列表、校验和与元数据的 XML 文件。aria2 可利用它自动寻找最快的镜像源，同时校验文件的完整性。

cli

# Download via a local metalink file $aria2c -M download.metalink # Download only specific files from a metalink (1, 3, and 5) $aria2c --select-file=1,3,5 http://example.org/files.metalink

文档 / 深入解析 / 身份验证与云存储

身份验证与云端免登录（Cookies）

许多现代镜像站点需要登录会话才能享受高级或私有带宽。您可以直接从 Google Chrome 或 Firefox 导出 cookies.txt 文件，并将其交给 aria2，从而即刻实现无头授权下载。

cli

# Impersonate your active browser session directly $aria2c --load-cookies=cookies.txt https://host/premium-file.rar # Standard HTTP Basic Auth $aria2c --http-user="admin" --http-passwd="password" http://...

文档 / 高级功能 / 断点续传

断点续传与恢复

与 wget 不同，aria2 具备非常强大的文件恢复能力。即使在大文件传输过程中断网或断电，也可以使用 -c / --continue 参数无缝恢复下载并校验数据。

cli

# Resume a broken download $aria2c -c http://example.org/mylinux.iso

如果不使用 -c 且文件已存在，aria2 默认会自动将新下载重命名为 mylinux.1.iso，以防止意外覆盖。

文档 / 高级功能 / 带宽限速

带宽限速

在后台下载时，可通过设置严格的限速来避免 aria2 占满家庭网络。限速既可全局应用于整个守护进程，也可针对单个任务单独设置。

cli

# Restrict the entire aria2 daemon to 2 megabytes per second $aria2c --max-overall-download-limit=2M -i urls.txt # Restrict EACH specific task to 500 kilobytes per second $aria2c --max-download-limit=500K http://example.org/hq.mp4

文档 / 高级功能 / 磁盘 I/O

磁盘预分配与高速 I/O

当通过 16 个并行分片连接下载 50GB 以上的大文件时，机械硬盘（以及普通 SSD）会出现严重的文件系统碎片，从而导致速度下降。

aria2 的 falloc 引擎可在下载开始前，直接在内核层面命令操作系统预先分配好数据块。

cli

# Pre-allocate blocks (Supported on Ext4, XFS, Btrfs, and NTFS) $aria2c --file-allocation=falloc http://example.org/50G.iso

文档 / 高级功能 / 校验和

校验和与完整性校验

可强制 aria2 在传输过程中或完成后校验哈希值，确保下载的文件未被损坏或篡改。

cli

# Verify MD5/SHA-256 hash immediately upon completion $aria2c --checksum=sha-256=HASH_STRING http://example.org/file.zip # Deep repair: Check existing file pieces and only download the broken ones $aria2c --check-integrity=true ubuntu.torrent

文档 / 网络配置 / IPv6

高级网络与 IPv6

可精细调整 aria2 绑定本地网卡的方式，特别适用于多网卡服务器或 VPN 环境。

cli

# Disable IPv6 if your network/ISP doesn't support it $aria2c --disable-ipv6=true http://example.org/file # Bind all traffic to a specific local interface (e.g., eth1) $aria2c --interface=eth1 http://example.org/file # Happy Eyeballs: Optimized IPv6/IPv4 fallback algorithm is used by default.

文档 / 网络配置 / 代理

代理配置

aria2 支持 HTTP 代理（HTTPS 通过 CONNECT 隧道），可跳过 SSL 证书校验，并支持显式绑定 IPv6。aria2 不支持 SOCKS 代理——如只有 SOCKS5 隧道，请使用 privoxy 或 gost 等 HTTP 转 SOCKS 桥接工具。

cli

# Route downloads through an HTTP proxy (aria2 has no SOCKS support) $aria2c --all-proxy="http://127.0.0.1:8080" http://example.org/ # Bypass untrusted SSL server certificate halts natively $aria2c --check-certificate=false https://raw-server.net/

文档 / 网络配置 / 安全

安全与加密

对于 BitTorrent 传输，您可以强制加密以防止运营商窥探或限速。还可以为 HTTPS 链接设置严格的 SSL 证书校验要求。

cli

# Require BitTorrent encryption (refuse non-encrypted peers) $aria2c --bt-require-crypto=true ubuntu.torrent # Use a specific CA certificate to verify the server $aria2c --ca-certificate=/path/to/ca.pem https://secure-server.com/

文档 / 自动化 / 守护进程

守护进程服务

将 aria2 完全脱离终端运行于后台。这是搭建 VPS、Seedbox 和无头服务器环境的必备方式。

cli

# Run as a background daemon process $aria2c --daemon=true --enable-rpc=true --conf-path=/etc/aria2.conf

提示：如果您希望以交互方式管理后台下载，而不想运行守护进程服务，可以将 aria2c 运行在独立的 tmux 会话中。

文档 / 自动化 / RPC

RPC 子系统（远程控制）

通过 JSON-RPC 接口，您可以从远程服务器、手机 App 或 AriaNg 等 Web 图形界面向 aria2 发送控制命令。

cli

# Start the RPC Server securely on port 6800 $aria2c --enable-rpc --rpc-listen-all --rpc-secret=mySecretToken # Simple curl call to add a download via RPC $curl -X POST -d '{"jsonrpc":"2.0","id":"q","method":"aria2.addUri","params":["token:mySecretToken",["URL"]]}' http://localhost:6800/jsonrpc

方法	描述
`aria2.addUri`	添加新的 HTTP/FTP/SFTP 下载任务。
`aria2.addTorrent`	通过上传 .torrent 文件添加 BitTorrent 下载任务。
`aria2.tellStatus`	返回指定 GID 的进度与状态。
`aria2.pauseAll`	立即暂停所有进行中的下载。
`aria2.getOption`	获取指定 GID 的配置参数。

文档 / 自动化 / 钩子

事件钩子与脚本

利用 aria2 内建的事件监听器触发自动化任务。您可以将文件路径、GID 等变量传递到外部 bash 环境中。

cli

# Trigger "unzip.sh" immediately upon successful 100% completion $aria2c --on-download-complete=/opt/scripts/unzip.sh http://...

文档 / 配置 / aria2.conf

完美的 `aria2.conf` 配置

在静态配置文件（通常为 ~/.aria2/aria2.conf）中定义固定的引擎参数，从而省去每次手动指定参数。

~/.aria2/aria2.conf

# --- Performance Tuning --- max-connection-per-server=16 split=16 file-allocation=falloc # --- RPC Server --- enable-rpc=true rpc-secret=YOUR_KEY # --- State --- save-session=~/.aria2/aria2.session input-file=~/.aria2/aria2.session

文档 / 配置 / 环境变量

环境变量

aria2 会自动读取终端配置文件中的标准系统代理变量。

变量	描述
`http_proxy`	HTTP 请求的默认代理。
`https_proxy`	HTTPS 请求的默认代理。
`all_proxy`	全局代理服务器。
`no_proxy`	不走代理直连的域名。

文档 / 参考 / 进度显示

理解控制台进度显示

控制台引擎实时输出的状态快照字符串。

cli

[#GID 123MB/456MB(27%) CN:16 DL:5.2MB UL:12KB ETA:1m45s]

GID: 任务唯一标识符。
CN: 当前连接数。
DL / UL: 当前下载 / 上传速度。
ETA: 预计剩余时间。

文档 / 参考 / 文件

技术文件与格式

底层使用的二进制布局与状态文件。

文件	用途
`dht.dat`	存储 DHT 路由表（二进制）。
`.netrc`	HTTP/FTP 自动登录凭据。
`aria2.session`	暂停 / 恢复的会话状态。
`*.aria2`	v1 版二进制控制文件（大端序）。

tips

Netrc 格式： machine example.com login user password password

文档 / 参考 / 状态码

退出状态码

在脚本中解析 $?，以优雅地处理失败情况。

代码	含义
0	成功
1	未知错误
3	404 未找到
9	磁盘已满

文档 / 参考 / 高阶用户

高阶技巧与单位