aria2c(1)¶

概要¶

aria2c [<选项>] [<URI>|<磁力链接>|<种子文件>|<Metalink 文件>] …

描述¶

aria2 是一个用于下载文件的实用工具。支持的协议包括 HTTP(S)、FTP、SFTP、BitTorrent 和 Metalink。 aria2 可以从多个源/协议下载文件，并尝试利用您的最大下载带宽。它支持同时从 HTTP(S)/FTP/SFTP 和 BitTorrent 下载文件，同时将从 HTTP(S)/FTP/SFTP 下载的数据上传到 BitTorrent 群。使用 Metalink 分块校验， aria2 在下载文件时会自动验证数据块。

选项¶

Note

大多数与 FTP 相关的选项也适用于 SFTP。一些选项对 SFTP 无效（例如， --ftp-pasv ）

基本选项¶

-d, --dir=<DIR>¶: 存储下载文件的目录。

-i, --input-file=<FILE>¶: 下载列在``FILE``中的 URI。您可以通过在单行上使用多个以 TAB 分隔的 URI 来为单个实体指定多个源。此外，可以在每个 URI 行后面指定选项。选项行必须以一个或多个空白字符（SPACE 或 TAB）开头，每行只能包含一个选项。输入文件可以使用 gzip 压缩。当将``FILE``指定为``-``时，aria2 将从``stdin``读取输入。有关详细信息，请参见`输入文件`_部分。还请参见:option:–deferred-input 选项。还请参见:option:–save-session 选项。

-l, --log=<LOG>¶: 日志文件的文件名。如果指定了``-，则日志将写入``stdout。如果指定了空字符串(“”)，或者省略了此选项，则根本不会将日志写入磁盘。

-j, --max-concurrent-downloads=<N>¶

设置每个队列项的最大并行下载数。还请参见:option:–split <-s> 选项。默认：5

Note

--max-concurrent-downloads 限制并行下载的项目数。--split 和:option:–min-split-size <-k> 可影响每个项目内的连接数。想象一下，您有一个输入文件（参见:option:–input-file <-i> 选项），例如：

http://example.com/foo
http://example.com/bar

这里有 2 个下载项。如果将值设置为大于或等于 2 的话，aria2 可以同时下载这些项。在每个下载项中，可以使用:option:–split <-s> 和/或:option:–min-split-size <-k> 配置连接数，等等。

-V, --check-integrity [true|false]¶: 通过验证分块哈希或整个文件的哈希来检查文件完整性。此选项仅在具有校验和的 BitTorrent、Metalink 下载或使用:option:–checksum 选项的 HTTP(S)/FTP 下载中生效。如果提供了分块哈希，此选项可以检测文件的损坏部分并重新下载它们。如果提供了整个文件的哈希，只有当文件已经下载时才会进行哈希检查。这是通过文件长度确定的。如果哈希检查失败，则从头开始重新下载文件。如果分块哈希和整个文件的哈希都提供了，那么只使用分块哈希。默认：false

-c, --continue [true|false]¶: 继续下载已部分下载的文件。使用此选项来恢复由网络浏览器或另一个程序开始的下载，该程序按顺序从头开始下载文件。当前，此选项仅适用于 HTTP(S)/FTP 下载。

-h, --help[=<TAG>|<KEYWORD>]¶: 帮助消息以标签进行分类。标签以``#``开头。例如，键入 --help=#http 以获取标记为 #http 的选项的用法。如果给出了非标签词，则打印包含该词的选项的用法。可用值：#basic、#advanced、#http、#https、#ftp、#metalink、#bittorrent、#cookie、#hook、#file、#rpc、#checksum、#experimental、#deprecated、#help、#all 默认：#basic

HTTP/FTP/SFTP 选项¶

--all-proxy=<PROXY>¶: 为所有协议使用代理服务器。要覆盖之前定义的代理，请使用 “”。您还可以覆盖此设置并为特定协议指定代理服务器，使用 --http-proxy、--https-proxy 和 --ftp-proxy 选项。这会影响所有下载操作。 PROXY 的格式为 [http://][USER:PASSWORD@]HOST[:PORT]。另请参见环境部分。

Note

如果用户和密码嵌入在代理 URI 中，并且它们也被 –{http,https,ftp,all}-proxy-{user,passwd} 选项指定，随后指定的选项会覆盖先前的选项。例如，如果您在 aria2.conf 中指定了 http-proxy-user=myname，http-proxy-passwd=mypass，并且在命令行上指定了 --http-proxy="http://proxy"，那么您将获得 HTTP 代理 http://proxy，用户为 myname，密码为 mypass。

另一个例子：如果您在命令行上指定了 --http-proxy="http://user:pass@proxy" --http-proxy-user="myname" --http-proxy-passwd="mypass"，那么您将获得 HTTP 代理 http://proxy，用户为 myname，密码为 mypass。

另一个例子：如果您在命令行上指定了 --http-proxy-user="myname" --http-proxy-passwd="mypass" --http-proxy="http://user:pass@proxy"，那么您将获得 HTTP 代理 http://proxy，用户为 user，密码为 pass。

--all-proxy-passwd=<PASSWD>¶: 为 --all-proxy 选项设置密码。

--all-proxy-user=<USER>¶: 为 --all-proxy 选项设置用户。

--checksum=<TYPE>=<DIGEST>¶: 设置校验和。TYPE 是哈希类型。支持的哈希类型在 aria2c -v 的 Hash Algorithms 中列出。DIGEST 是十六进制摘要。例如，设置 sha-1 摘要如下所示：sha-1=0192ba11326fe2298c8cb4de616f4d4140213838。此选项仅适用于 HTTP(S)/FTP 下载。

--connect-timeout=<SEC>¶: 设置在多少秒内建立到 HTTP/FTP/代理服务器的连接的超时时间。连接建立后，此选项不起作用，而是使用 --timeout 选项。默认值：60

--dry-run [true|false]¶: 如果给定 true，aria2 只检查远程文件是否可用，不会下载数据。此选项会影响 HTTP/FTP 下载。如果指定了 true，BitTorrent 下载将被取消。默认值：false

--lowest-speed-limit=<SPEED>¶: 如果下载速度低于或等于此值（每秒字节数），则关闭连接。0 表示 aria2 没有最低速度限制。您可以附加 K 或 M``（1K = 1024，1M = 1024K）。此选项不会影响 BitTorrent 下载。默认值：``0

-x, --max-connection-per-server=<NUM>¶: 每个下载的服务器的最大连接数。默认值：1

--max-file-not-found=<NUM>¶

如果 aria2 从远程 HTTP/FTP 服务器接收到 “file not found” 状态 NUM 次，且没有获取到单个字节，则强制下载失败。指定 0 可禁用此选项。此选项仅在使用 HTTP/FTP 服务器时有效。重试尝试次数计入 --max-tries，因此也应配置该选项。

默认值：0

-m, --max-tries=<N>¶: 设置重试次数。0 表示无限次。另请参见 --retry-wait。默认值：5

-k, --min-split-size=<SIZE>¶: aria2 不会将文件划分为小于 2*SIZE 字节的范围。例如，假设下载 20MiB 文件。如果 SIZE 为 10M，aria2 可以将文件划分为 2 个范围 [0-10MiB) 和 [10MiB-20MiB)，并使用 2 个来源下载它（如果 --split >= 2，当然）。如果 SIZE 为 15M，因为 2*15M > 20MiB，aria2 不会划分文件，并使用 1 个来源下载。您可以附加 K 或 M``（1K = 1024，1M = 1024K）。可能的值：``1M - 1024M 默认值：20M

--netrc-path=<FILE>¶: 指定 netrc 文件的路径。默认值：$(HOME)/.netrc

Note

.netrc 文件的权限必须为 600。否则，文件将被忽略。

-n, --no-netrc [true|false]¶: 禁用 netrc 支持。netrc 支持默认启用。

Note

如果 --no-netrc 为 false，netrc 文件只在启动时读取。因此，如果 --no-netrc 在启动时为 true，则在整个会话期间都不可用 netrc。即使您发送 --no-netrc=false 使用 aria2.changeGlobalOption()，也无法启用 netrc。

--no-proxy=<DOMAINS>¶: 指定一个由逗号分隔的主机名、域名和网络地址列表，这些地址带有或不带有子网掩码，不应使用代理。

Note

对于带有子网掩码的网络地址，IPv4 和 IPv6 地址都有效。当前实现不会解析 URI 中的主机名以比较 --no-proxy 中指定的网络地址。因此，只有在 URI 具有数字 IP 地址时，此选项才有效。

-o, --out=<FILE>¶

下载文件的文件名。它始终是相对于 --dir 选项中给定的目录。使用 --force-sequential 选项时，此选项将被忽略。

Note

您无法为 Metalink 或 BitTorrent 下载指定文件名。此处指定的文件名仅在直接在命令行上提供 URI 时使用，而在使用 --input-file、--force-sequential 选项时不使用。

例如：

$ aria2c -o myfile.zip "http://mirror1/file.zip" "http://mirror2/file.zip"

--proxy-method=<METHOD>¶: 设置在代理请求中使用的方法。METHOD 是 get 或 tunnel。无论此选项如何设置，HTTPS 下载始终使用 tunnel。默认值：get

-R, --remote-time [true|false]¶: 从远程 HTTP/FTP 服务器检索远程文件的时间戳，如果可用，将其应用于本地文件。默认值：false

--reuse-uri [true|false]¶: 如果没有未使用的 URI，则重用已使用的 URI。默认值：true

--retry-wait=<SEC>¶: 设置重试之间等待的秒数。当``SEC > 0`` 时，如果 HTTP 服务器返回 503 响应，aria2 将重试下载。默认值：0

--server-stat-of=<FILE>¶: 指定保存服务器性能概要的文件名。您可以使用 --server-stat-if 选项加载保存的数据。请参阅下文的服务器性能配置文件子部分，了解文件格式。

--server-stat-if=<FILE>¶: 指定要加载的服务器性能概要的文件名。加载的数据将在某些 URI 选择器中使用，例如 feedback。另请参阅 --uri-selector 选项。请参阅下文的服务器性能配置文件子部分，了解文件格式。

--server-stat-timeout=<SEC>¶: 指定自上次与服务器联系以来，服务器性能概要超时的秒数。默认值：``86400``（24 小时）

-s, --split=<N>¶: 使用 N 个连接下载文件。如果给出的 URI 超过 N 个，将使用前 N 个 URI，其余的用作备用。如果给出的 URI 不到 N 个，那么这些 URI 将被再次使用，以便总共同时建立 N 个连接。对同一服务器的连接数受 --max-connection-per-server 选项的限制。也请参阅 --min-split-size 选项。默认值：5

Note

一些 Metalink 规定了要连接的服务器数量。aria2 严格遵守这些规定。这意味着如果 Metalink 定义的 maxconnections 属性小于 N，则 aria2 将使用该较低值，而不是 N。

--stream-piece-selector=<SELECTOR>¶

指定在 HTTP/FTP 下载中使用的片段选择算法。片段是分段下载中并行下载的固定长度片段。默认值：default。

default: 选择一个片段以减少建立的连接数。这是合理的默认行为，因为建立连接是一个昂贵的操作。
inorder: 选择最接近文件开头的片段。这对于在下载时观看电影很有用。 --enable-http-pipelining 选项可能有助于减少重新连接开销。请注意，aria2 遵守 --min-split-size 选项，因此必须为 --min-split-size 选项指定一个合理的值。
random: 随机选择一个片段。与 inorder 一样，也遵守 --min-split-size 选项。
geom: 在开始下载文件时，选择最接近文件开头的片段，然后指数增加片段之间的间隔。这减少了建立的连接数，同时首先下载文件的开始部分。这对于在下载时观看电影很有用。

-t, --timeout=<SEC>¶: 设置超时的秒数。默认值：60

--uri-selector=<SELECTOR>¶: 指定 URI 选择算法。可能的值为 inorder、feedback 和 adaptive。如果给出 inorder，将按照 URI 列表中出现的顺序尝试 URI。如果给出 feedback，aria2 使用先前下载中观察到的下载速度，并选择 URI 列表中最快的服务器。这也有效地跳过了死掉的镜像。观察到的下载速度是 --server-stat-of 和 --server-stat-if 选项所提到的服务器性能概要的一部分。如果给出 adaptive，选择最佳镜像用于首部连接，保留连接。对于补充镜像，返回已经未测试的镜像，如果每个镜像都已经被测试，则返回需要再次测试的镜像。否则，不再选择镜像。与 feedback 一样，它使用服务器的性能概要。默认值：feedback

HTTP特定选项¶

--ca-certificate=<FILE>¶: 使用文件中的证书机构来验证对等方。证书文件必须以PEM格式提供，并且可以包含多个CA证书。使用:option:`–check-certificate`选项来启用验证。

Note

如果使用 OpenSSL 或具有 gnutls_certificate_set_x509_system_trust() 函数的最新版本的 GnuTLS 并且库已正确配置以定位系统范围内的CA 证书存储，则 aria2 将在启动时自动加载这些证书。

Note

WinTLS 和 AppleTLS 不支持此选项。相反，您需要将证书导入系统信任存储区。

--certificate=<FILE>¶

使用文件中的客户端证书。证书必须是 PKCS12(.p12, .pfx) 格式或 PEM 格式。

PKCS12文件必须包含证书、密钥，以及可选的额外证书链。只能打开空白导入密码的 PKCS12 文件！

使用 PEM 格式时，您还必须通过 --private-key 指定私钥。

Note

WinTLS 目前不支持 PEM 文件。用户必须使用 PKCS12 文件。

Note

AppleTLS 用户应使用 KeyChain Access 实用程序导入客户端证书，并从对应于该证书的信息对话框中获取 SHA-1 指纹。要启动 aria2c，请使用 –certificate=<SHA-1>。此外，也支持 PEM 文件，但不支持 PEM 文件。

--check-certificate [true|false]¶: 使用 --ca-certificate 选项指定的证书来验证对等方。默认值：true

--http-accept-gzip [true|false]¶: 发送 Accept-Encoding: deflate, gzip 请求头，并在远程服务器以 Content-Encoding: gzip 或 Content-Encoding: deflate 响应时解压缩响应内容。默认值：false

Note

一些服务器对其本身就是压缩文件的文件响应 Content-Encoding: gzip。aria2 仍会进行解压缩，因为响应头中包含了此信息。

--http-auth-challenge [true|false]¶: 只有在服务器请求时才发送HTTP授权头。如果设置为 false，则授权头总是发送到服务器。有一个例外：如果用户名和密码嵌入在URI中，则无论此选项如何设置，授权头都将始终发送到服务器。默认值：false

--http-no-cache [true|false]¶: 发送 Cache-Control: no-cache 和 Pragma: no-cache 头以避免缓存内容。如果给定 false，则不发送这些头，您可以使用 --header 选项添加您喜欢的指令的Cache-Control头。默认值：false

--http-user=<USER>¶: 设置HTTP用户名。这会影响所有的URI。

--http-passwd=<PASSWD>¶: 设置HTTP密码。这会影响所有的URI。

--http-proxy=<PROXY>¶: 为HTTP使用代理服务器。要覆盖之前定义的代理，使用空字符串””。也请参阅:option:–all-proxy 选项。这会影响所有的http下载。 PROXY的格式是``[http://][USER:PASSWORD@]HOST[:PORT]``

--http-proxy-passwd=<PASSWD>¶: 为 --http-proxy 设置密码。

--http-proxy-user=<USER>¶: 为 --http-proxy 设置用户。

--https-proxy=<PROXY>¶: 为HTTPS使用代理服务器。要覆盖之前定义的代理，使用空字符串””。也请参阅:option:–all-proxy 选项。这会影响所有的https下载。 PROXY的格式是``[http://][USER:PASSWORD@]HOST[:PORT]``

--https-proxy-passwd=<PASSWD>¶: 为 --https-proxy 设置密码。

--https-proxy-user=<USER>¶: 为 --https-proxy 设置用户。

--private-key=<FILE>¶: 使用文件中的私钥。私钥必须是未加密的并且以PEM格式提供。加密的密钥可能会导致未定义的行为。参见:option:–certificate 选项。

--referer=<REFERER>¶: 设置HTTP引用者(Referer)。这会影响所有的http/https下载。如果给定``*``，则下载的URI也会被用作引用者。当与:option:–parameterized-uri <-P> 选项一起使用时，这可能会很有用。

--enable-http-keep-alive [true|false]¶: 启用HTTP/1.1持久连接。默认值：true

--enable-http-pipelining [true|false]¶: 启用HTTP/1.1流水线处理。默认值：false

Note

通常情况下，启用此选项并不会带来性能提升。

--header=<HEADER>¶

将HEADER追加到HTTP请求头。您可以重复使用此选项来指定不止一个头：

$ aria2c --header="X-A: b78" --header="X-B: 9J1" "http://host/file"

--load-cookies=<FILE>¶: 使用Firefox3格式(SQLite3)、Chromium/Google Chrome (SQLite3)和Mozilla/Firefox(1.x/2.x)/Netscape 格式从文件加载Cookie。

Note

如果 aria2 是没有构建时 libsqlite3，那么它不支持Firefox3和Chromium/Google Chrome的cookie格式。

--save-cookies=<FILE>¶: 以Mozilla/Firefox(1.x/2.x)/ Netscape的格式保存Cookie到文件。如果 FILE 已经存在，则会被覆盖。会话Cookie也会被保存，并且它们的过期值被视为0。可能的取值：/path/to/file

--use-head [true|false]¶: 对HTTP服务器的第一个请求使用HEAD方法。默认值：false

--no-want-digest-header [true|false]¶: 在进行请求时是否禁用Want-Digest头的设置。默认值：false

-U, --user-agent=<USER_AGENT>¶: 设置HTTP(S)下载的用户代理。默认值：aria2/$VERSION，$VERSION 会被软件版本替换。

特定的FTP/SFTP选项¶

--ftp-user=<USER>¶: 设置FTP用户名。这会影响所有的URI。默认值: anonymous

--ftp-passwd=<PASSWD>¶: 设置FTP密码。这会影响所有的URI。如果用户名嵌入在URI中，但密码在其中缺失，aria2会尝试使用 .netrc 解析密码。如果在 .netrc 中找到了密码，就会使用那个密码。如果没有找到，则使用此选项中指定的密码。默认值: ARIA2USER@

-p, --ftp-pasv [true|false]¶: 在FTP中使用被动模式。如果提供了``false``，则会使用主动模式。默认值: true

Note

对于SFTP传输，此选项将被忽略。

--ftp-proxy=<PROXY>¶: 为FTP使用代理服务器。要覆盖先前定义的代理，使用””。也可以参见:option:–all-proxy`选项。这会影响所有的FTP下载。 PROXY的格式为``[http://][USER:PASSWORD@]HOST[:PORT]`

--ftp-proxy-passwd=<PASSWD>¶: 为:option:`–ftp-proxy`选项设置密码。

--ftp-proxy-user=<USER>¶: 为:option:`–ftp-proxy`选项设置用户。

--ftp-type=<TYPE>¶: 设置FTP传输类型。TYPE可以是``binary``或``ascii``。默认值: binary

Note

对于SFTP传输，此选项将被忽略。

--ftp-reuse-connection [true|false]¶: 在FTP中重用连接。默认值: true

--ssh-host-key-md=<TYPE>=<DIGEST>¶: 设置SSH主机公钥的校验和。TYPE是哈希类型。支持的哈希类型有``sha-1``或``md5``。DIGEST是十六进制摘要。例如: sha-1=b030503d4de4539dc7885e6f0f5e256704edf4c3。此选项可用于在使用SFTP时验证服务器的公钥。如果未设置此选项，默认情况下不会进行验证。

BitTorrent/Metalink 选项¶

--select-file=<INDEX>...¶: 通过指定索引来设置要下载的文件。您可以使用 --show-files 选项来找到文件索引。可以通过使用 , 指定多个索引，例如：3,6。您还可以使用 - 来指定一个范围：1-5。 , 和 - 可以一起使用：1-5,8,9。在使用 -M 选项时，索引可能会根据查询而变化 (参见 –metalink-* 选项)。

Note

在多文件种子中，此选项指定的相邻文件也可能会被下载。这是设计如此，而不是一个错误。单个文件块可能包含多个文件或部分文件，aria2 将文件块写入适当的文件。

-S, --show-files [true|false]¶: 打印“.torrent”、“meta4”和“.metalink”文件的文件列表并退出。对于“.torrent”文件，还会打印额外的信息 (infohash, piece length, etc)。

BitTorrent 特定选项¶

--bt-detach-seed-only [true|false]¶: 在计算并发活动下载（参见 -j 选项）时排除仅种子下载。这意味着如果给定了 -j3 并且此选项已打开，则有 3 个下载正在进行并且其中一个进入了种子模式，则它会被排除在活动下载计数之外（因此它变为 2），并且队列中的下一个下载将开始。但请注意，种子项目仍然在 RPC 方法中被视为活动下载。默认值：false

--bt-enable-hook-after-hash-check [true|false]¶: 在 BitTorrent 下载中允许在哈希检查后（参见 -V 选项）调用挂钩命令。默认情况下，当哈希检查成功时，将执行 --on-bt-download-complete 给定的命令。要禁用此操作，请将此选项设为 false。默认值：true

--bt-enable-lpd [true|false]¶: 启用局部对等发现。如果种子中设置了私有标记，则 aria2 不会为该下载使用此功能，即使给定了 true。默认值：false

--bt-exclude-tracker=<URI>[,...]¶: 要移除的 BitTorrent tracker 的通告 URI 的逗号分隔列表。可以使用特殊值 * 匹配所有 URI，因此移除所有通告 URI。在命令行中指定 * 时，请不要忘记对其进行转义或引用。也请参见 --bt-tracker 选项。

--bt-external-ip=<IPADDRESS>¶: 指定在 BitTorrent 下载和 DHT 中要使用的外部 IP 地址。可能会发送到 BitTorrent 跟踪器。对于 DHT，应设置此选项以报告本地节点正在下载特定的种子。在私有网络中使用 DHT 是至关重要的。尽管此功能命名为“外部”，但它可以接受任何类型的 IP 地址。

--bt-force-encryption [true|false]¶: 要求使用 arc4 进行 BitTorrent 消息有效载荷加密。这是 --bt-require-crypto 和 --bt-min-crypto-level=arc4 的简写。此选项不会更改这些选项的值。如果给定了 true，则拒绝传统的 BitTorrent 握手，仅使用混淆握手并始终加密消息有效载荷。默认值：false

--bt-hash-check-seed [true|false]¶: 如果给定了 true，则在使用 --check-integrity 选项进行哈希检查后，文件完整后，继续对文件进行做种。如果要检查文件并仅在文件损坏或不完整时才下载它，请将此选项设置为 false。此选项仅在 BitTorrent 下载中生效。默认值：true

--bt-load-saved-metadata [true|false]¶: 在使用磁力链接下载时，从 DHT 获取种子元数据之前，首先尝试读取由 --bt-save-metadata 选项保存的文件。如果成功，然后跳过从 DHT 下载元数据。默认值：false

--bt-lpd-interface=<INTERFACE>¶: 为局部对等发现使用给定界面。如果未指定此选项，则选择默认界面。您可以指定界面名称和 IP 地址。可能的值：界面、IP 地址

--bt-max-open-files=<NUM>¶: 全局指定多文件 BitTorrent/Metalink 下载要打开的最大文件数。默认值：100

--bt-max-peers=<NUM>¶: 指定每个种子的最大对等数。 0 表示无限制。也请参见 --bt-request-peer-speed-limit 选项。默认值：55

--bt-metadata-only [true|false]¶: 仅下载元数据，不会下载元数据中描述的文件。此选项仅在使用 BitTorrent 磁力链接时生效。也请参见 --bt-save-metadata 选项。默认值：false

--bt-min-crypto-level=plain|arc4¶: 设置加密方法的最低级别。如果对等端提供了多种加密方法，aria2 会选择满足给定级别的最低级别的一个。默认值：plain

--bt-prioritize-piece=head[=<SIZE>],tail[=<SIZE>]¶: 首先尝试下载每个文件的第一个和最后一个片段。这对于预览文件非常有用。参数中可以包含 2 个关键字：head 和 tail。要包括这两个关键字，它们必须用逗号分隔。这些关键字可以带一个参数 SIZE。例如，如果指定了 head=<SIZE>，则每个文件的前 SIZE 字节范围内的片段会获得更高的优先级。 tail=<SIZE> 表示每个文件的最后 SIZE 字节的范围。SIZE 可以包括 K 或 ``M``（1K = 1024，1M = 1024K）。如果省略了 SIZE，则使用 SIZE=1M。

--bt-remove-unselected-file [true|false]¶: 在 BitTorrent 完成下载时移除未选中的文件。要选择文件，请使用 --select-file 选项。如果未使用此选项，则假定所有文件均为选定。请谨慎使用此选项，因为它实际上会从您的磁盘中删除文件。默认值：false

--bt-require-crypto [true|false]¶: 如果给定了 true，aria2 不会接受并建立与传统的 BitTorrent 握手（19 BitTorrent 协议）的连接。因此，aria2 始终使用混淆握手。默认值：false

--bt-request-peer-speed-limit=<SPEED>¶: 如果每个种子的整体下载速度低于 SPEED，aria2 会暂时增加对等节点的数量，以尝试获得更多的下载速度。使用您首选的下载速度配置此选项，有时可以提高您的下载速度。您可以附加 K 或 M``（1K = 1024，1M = 1024K）。默认值：``50K

--bt-save-metadata [true|false]¶: 保存元数据为”.torrent”文件。此选项仅在使用BitTorrent Magnet URI时有效。文件名为十六进制编码的信息哈希，后缀为”.torrent”。要保存的目录与下载文件保存在相同的目录中。如果相同的文件已经存在，则不保存元数据。另请参阅 --bt-metadata-only 选项。默认值：false

--bt-seed-unverified [true|false]¶: 在不验证分片哈希的情况下进行种子先前下载的文件。默认值：false

--bt-stop-timeout=<SEC>¶: 如果连续SEC秒内下载速度为0，则停止BitTorrent下载。如果给定``0``，则禁用此功能。默认值：0

--bt-tracker=<URI>[,...]¶: 附加BitTorrent跟踪器的公告URI的逗号分隔列表。这些URI不受 --bt-exclude-tracker 选项的影响，因为它们是在移除 --bt-exclude-tracker 选项中的URI之后添加的。

--bt-tracker-connect-timeout=<SEC>¶: 设置连接到跟踪器的连接超时时间（以秒为单位）。连接建立后，此选项将不起作用，而是使用 --bt-tracker-timeout 选项。默认值：60

--bt-tracker-interval=<SEC>¶: 设置跟踪器请求之间的间隔时间（以秒为单位）。这将完全覆盖间隔值，aria2将仅使用此值并忽略跟踪器响应中的最小间隔和间隔值。如果设置为``0``，aria2将根据跟踪器的响应和下载进度确定间隔。默认值：0

--bt-tracker-timeout=<SEC>¶: 设置超时时间（以秒为单位）。默认值：60

--dht-entry-point=<HOST>:<PORT>¶: 将主机和端口设置为IPv4 DHT网络的入口点。

--dht-entry-point6=<HOST>:<PORT>¶: 将主机和端口设置为IPv6 DHT网络的入口点。

--dht-file-path=<PATH>¶: 将IPv4 DHT路由表文件更改为路径。默认值：如果存在，则为``$HOME/.aria2/dht.dat``，否则为``$XDG_CACHE_HOME/aria2/dht.dat``。

--dht-file-path6=<PATH>¶: 将IPv6 DHT路由表文件更改为路径。默认值：如果存在，则为``$HOME/.aria2/dht6.dat``，否则为``$XDG_CACHE_HOME/aria2/dht6.dat``。

--dht-listen-addr6=<ADDR>¶: 指定IPv6 DHT绑定套接字的地址。它应该是主机的全球单播IPv6地址。

--dht-listen-port=<PORT>...¶: 设置DHT（IPv4、IPv6）和UDP跟踪器使用的UDP监听端口。可以使用`,`来指定多个端口，例如：6881,6885。您还可以使用``-来指定范围：``6881-6999。,`和`-可以一起使用。默认值：``6881-6999

Note

请确保指定的端口对于传入的UDP流量是打开的。

--dht-message-timeout=<SEC>¶: 设置超时时间（以秒为单位）。默认值：10

--enable-dht [true|false]¶: 启用IPv4 DHT功能。这也启用UDP跟踪器支持。如果torrent中设置了私有标志，则aria2不会使用DHT来下载该文件，即使给定``true``也是如此。默认值：true

--enable-dht6 [true|false]¶: 启用IPv6 DHT功能。如果torrent中设置了私有标志，则aria2不会使用DHT来下载该文件，即使给定``true``也是如此。使用 --dht-listen-port 选项来指定要侦听的端口号。另请参阅 --dht-listen-addr6 选项。

--enable-peer-exchange [true|false]¶: 启用Peer Exchange扩展。如果torrent中设置了私有标志，即使给定``true``也会禁用该功能。默认值：true

--follow-torrent=true|false|mem¶: 如果指定为``true``或``mem``，当下载文件的后缀为``.torrent``或内容类型为``application/x-bittorrent``时，aria2会将其解析为一个torrent文件，并下载其中提到的文件。如果指定为``mem``，则torrent文件不会写入磁盘，而只会保存在内存中。如果指定为``false``，.torrent``文件将会被下载到磁盘，但不会被解析为torrent并且其中的内容也不会被下载。默认值：``true

-O, --index-out=<INDEX>=<PATH>¶: 为索引INDEX的文件设置文件路径。您可以使用 --show-files 选项找到文件索引。PATH是相对于 --dir 选项中指定路径的相对路径。您可以多次使用此选项。使用此选项，您可以指定BitTorrent下载的输出文件名称。

--listen-port=<PORT>...¶: 设置BitTorrent下载的TCP端口号。可以使用`,`指定多个端口，例如：6881,6885。您还可以使用``-来指定范围：``6881-6999。,`和`-可以一起使用：``6881-6889,6999。默认值：6881-6999

Note

请确保指定的端口对于传入的TCP流量是打开的。

--max-overall-upload-limit=<SPEED>¶: 设置最大总上传速度，单位为字节/秒。0``表示无限制。您可以附加``K``或``M``（1K = 1024，1M = 1024K）。要限制每个种子的上传速度，请使用 :option:`--max-upload-limit <-u>` 选项。默认值：``0

-u, --max-upload-limit=<SPEED>¶: 设置每个种子的最大上传速度，单位为字节/秒。0``表示无限制。您可以附加``K``或``M``（1K = 1024，1M = 1024K）。要限制总上传速度，请使用 :option:`--max-overall-upload-limit` 选项。默认值：``0

--peer-id-prefix=<PEER_ID_PREFIX>¶

指定对等ID的前缀。BitTorrent中的对等ID是20字节长度。如果指定的字节数多于20字节，则只使用前20字节。如果指定的字节数少于20字节，则添加随机字节数据以使其长度达到20字节。

默认值：A2-$MAJOR-$MINOR-$PATCH-，$MAJOR、$MINOR和$PATCH分别由主要、次要和补丁版本号替换。例如，aria2版本1.18.8具有前缀ID``A2-1-18-8-``。

--peer-agent=<PEER_AGENT>¶

指定在对等方的客户端版本进行Bittorrent扩展握手期间使用的字符串。

默认值：aria2/$MAJOR.$MINOR.$PATCH，$MAJOR、$MINOR和$PATCH分别由主要、次要和补丁版本号替换。例如，aria2版本1.18.8的对等代理为``aria2/1.18.8``。

--seed-ratio=<RATIO>¶

指定共享比率。种子完成的种子直到共享比率达到RATIO。强烈建议您在这里指定等于或大于``1.0``。

如果希望进行种子共享而不考虑共享比率，请指定``0.0``。如果同时指定 --seed-time 选项，则在满足其中至少一项条件时种子结束。

默认值：1.0

--seed-time=<MINUTES>¶: 指定以（分数）分钟为单位的种子时间。另请参阅 --seed-ratio 选项。

Note

指定 --seed-time=0 将在下载完成后禁用种子。

-T, --torrent-file=<TORRENT_FILE>¶: “.torrent”文件的路径。您不需要使用此选项，因为您可以在不使用 --torrent-file 的情况下指定”.torrent”文件。

Metalink特定选项¶

--follow-metalink=true|false|mem¶: 如果指定为``true``或``mem``，当下载后缀为``.meta4``或``.metalink``或内容类型为``application/metalink4+xml``或``application/metalink+xml``的文件时，aria2会将其解析为metalink文件并下载其中提到的文件。如果指定为``mem``，metalink文件不会写入磁盘，而是保留在内存中。如果指定为``false``，则``.metalink``文件会下载到磁盘，但不会被解析为metalink文件，其中的内容也不会被下载。默认值：true

--metalink-base-uri=<URI>¶: 指定基本URI，以解析存储在本地磁盘上的metalink文件中的metalink:url和metalink:metaurl元素中的相对URI。如果URI指向目录，则URI必须以``/``结尾。

-M, --metalink-file=<METALINK_FILE>¶: .meta4``和.metalink``文件的文件路径。当指定为``-时从``stdin``读取输入。您不必使用此选项，因为可以在不使用:option:`--metalink-file <-M>`的情况下指定.metalink``文件。

--metalink-language=<LANGUAGE>¶: 要下载的文件的语言。

--metalink-location=<LOCATION>[,...]¶: 首选服务器的位置。可接受使用逗号分隔的位置列表，例如，jp,us。

--metalink-os=<OS>¶: 要下载的文件的操作系统。

--metalink-version=<VERSION>¶: 要下载的文件的版本。

--metalink-preferred-protocol=<PROTO>¶: 指定首选协议。可能的值为``http``、https、ftp``和``none。指定``none``以禁用此功能。默认值：none

--metalink-enable-unique-protocol [true|false]¶: 如果给定``true``并且metalink文件中为镜像提供了多个协议，aria2将使用其中之一。使用:option:–metalink-preferred-protocol`选项来指定协议的首选项。默认值：``true`

RPC选项¶

--enable-rpc [true|false]¶: 启用JSON-RPC/XML-RPC服务器。强烈建议使用:option:–rpc-secret`选项设置安全授权令牌。另请参见:option:–rpc-listen-port`选项。默认值：false

--pause [true|false]¶: 在添加后暂停下载。此选项仅在给出:option:–enable-rpc=true <–enable-rpc>`时有效。默认值：``false`

--pause-metadata [true|false]¶: 暂停作为元数据下载结果创建的下载。aria2中有三种类型的元数据下载：(1)下载.torrent文件。(2)使用磁力链接下载种子元数据。(3)下载metalink文件。这些元数据下载将生成使用其元数据的下载。此选项暂停这些后续下载。此选项仅在给出:option:–enable-rpc=true <–enable-rpc>`时有效。默认值：``false`

--rpc-allow-origin-all [true|false]¶: 在RPC响应中添加Access-Control-Allow-Origin标题字段，其值为``*``。默认值：false

--rpc-certificate=<FILE>¶

使用文件中的证书为RPC服务器进行认证。证书必须是PKCS12(.p12, .pfx)格式或PEM格式。

PKCS12文件必须包含证书、密钥，以及可选的额外证书链。只有空白导入密码的PKCS12文件才能被打开！

在使用PEM时，您还必须通过:option:–rpc-private-key`指定私钥。使用:option:–rpc-secure`选项启用加密。

Note

*WinTLS*目前不支持PEM文件。用户必须使用PKCS12文件。

Note

*AppleTLS*用户应使用KeyChain Access实用程序首先生成自签名的SSL服务器证书，例如使用向导，并获取与该新证书对应的信息对话框中的SHA-1指纹。要使用:option:–rpc-secure`启动aria2c，使用`–rpc-certificate=<SHA-1>``。另外，也支持PKCS12文件，但不支持PEM文件。

--rpc-listen-all [true|false]¶: 监听所有网络接口上的JSON-RPC/XML-RPC请求。如果给定false，则仅在本地回环接口上监听。默认值：false

--rpc-listen-port=<PORT>¶: 指定用于JSON-RPC/XML-RPC服务器监听的端口号。可能的值：1024-65535 默认值：6800

--rpc-max-request-size=<SIZE>¶: 设置JSON-RPC/XML-RPC请求的最大大小。如果aria2检测到请求超过SIZE字节，它会丢弃连接。默认值：2M

--rpc-passwd=<PASSWD>¶: 设置JSON-RPC/XML-RPC密码。

Warning

--rpc-passwd 选项将在将来版本中被弃用。尽快迁移到:option:`–rpc-secret`选项。

--rpc-private-key=<FILE>¶: 使用文件中的私钥为RPC服务器进行认证。私钥必须解密并且是PEM格式。使用:option:–rpc-secure`选项启用加密。另请参见:option:–rpc-certificate`选项。

--rpc-save-upload-metadata [true|false]¶: 在由:func:aria2.addTorrent`或:func:`aria2.addMetalink`添加的下载不会被:option:–save-session`选项保存时，将上传的torrent或metalink元数据保存在由:option:–dir`选项指定的目录中。文件名由元数据的SHA-1哈希十六进制字符串加上扩展名组成。对于torrent，扩展名为’.torrent’。对于metalink，扩展名为’.meta4’。如果给定``false`，则不会通过:option:–save-session`选项保存由此选项添加的下载。默认值：``true`

--rpc-secret=<TOKEN>¶: 设置RPC安全授权令牌。阅读:ref:`rpc_auth`了解如何使用该选项值。

--rpc-secure [true|false]¶: RPC传输将通过SSL/TLS加密。RPC客户端必须使用https方案访问服务器。对于WebSocket客户端，则使用wss方案。使用:option:–rpc-certificate`和 :option:–rpc-private-key`选项指定服务器证书和私钥。

--rpc-user=<USER>¶: 设置JSON-RPC/XML-RPC用户。

Warning

--rpc-user 选项将在将来版本中被弃用。尽快迁移到:option:`–rpc-secret`选项。

高级选项¶

--allow-overwrite [true|false]¶: 如果相应的控制文件不存在，则从头重新开始下载。另请参阅 --auto-file-renaming 选项。默认值为 false

--allow-piece-length-change [true|false]¶: 如果给出 false，则当分片长度与控制文件中的分片长度不同时，aria2 会中止下载。如果给出 true，则可以继续，但有些下载进度将丢失。默认值为 false

--always-resume [true|false]¶: 始终恢复下载。如果给出 true，aria2 总是尝试恢复下载，如果无法恢复，则中止下载。如果给出 false，当所有给定的 URI 不支持恢复或 aria2 遇到 N 个不支持恢复的 URI（N 是使用 --max-resume-failure-tries 选项指定的值）时，aria2 会从头下载文件。参见 --max-resume-failure-tries 选项。默认值为 true

--async-dns [true|false]¶: 启用异步 DNS。默认值为 true

--async-dns-server=<IP地址>[,...]¶: 异步 DNS 解析器使用的逗号分隔的 DNS 服务器地址列表。通常，异步 DNS 解析器会从 /etc/resolv.conf 读取 DNS 服务器地址。使用此选项时，它会使用此选项中指定的 DNS 服务器，而不是 /etc/resolv.conf 中的 DNS 服务器。您可以同时指定 IPv4 和 IPv6 地址。当系统没有 /etc/resolv.conf 且用户没有权限创建它时，此选项很有用。

--auto-file-renaming [true|false]¶: 如果已存在相同的文件，则重命名文件名。此选项仅在 HTTP(S)/FTP 下载时有效。新文件名在名称之后添加一个点和一个数字（1 到 9999），然后是文件扩展名（如果有）。默认值为 true

--auto-save-interval=<秒>¶: 每隔 SEC 秒保存一个控制文件（*.aria2）。如果给出 0，则在下载期间不保存控制文件。无论值如何，aria2 在停止时都会保存控制文件。可能的值介于 0 和 600 之间。默认值为 60

--conditional-get [true|false]¶: 仅在本地文件较旧时才下载文件。此功能仅在 HTTP(S) 下载中有效。如果 Metalink 中指定了文件大小，则此功能不起作用。它还会忽略 Content-Disposition 标头。如果存在控制文件，则将忽略此选项。此功能使用 If-Modified-Since 标头有条件地获取新文件。在获取本地文件的修改时间时，它使用用户提供的文件名（参见 --out 选项）或者如果未指定 --out，则使用 URI 中的文件名部分。要覆盖现有文件，需要 --allow-overwrite。默认值为 false

--conf-path=<路径>¶: 将配置文件路径更改为 PATH。默认值为 $HOME/.aria2/aria2.conf``（如果存在），否则为 ``$XDG_CONFIG_HOME/aria2/aria2.conf。

--console-log-level=<级别>¶: 将日志级别输出到控制台。LEVEL 可以是 debug、info、notice、warn 或 error。默认值为 notice

--content-disposition-default-utf8 [true|false]¶: 将 Content-Disposition 标头中的带引号字符串处理为 UTF-8 而不是 ISO-8859-1，例如，文件名参数，但不包括扩展版本的文件名*。默认值为 false

-D, --daemon [true|false]¶: 作为守护程序运行。当前工作目录将更改为 /，标准输入、标准输出和标准错误将被重定向到 /dev/null。默认值为 false

--deferred-input [true|false]¶: 如果给出 true，aria2 在启动时不会从 --input-file 选项指定的文件中一次性读取所有 URI 和选项，而是在以后需要时逐个读取。如果给出 false，aria2 在启动时会一次性读取所有 URI 和选项。默认值为 false

Warning

当同时使用 --save-session 时，将禁用 --deferred-input 选项。

--disable-ipv6 [true|false]¶: 禁用 IPv6。如果您必须使用错误的 DNS 并希望避免非常缓慢的 AAAA 记录查找，则此选项很有用。默认值为 false

--disk-cache=<大小>¶: 启用磁盘缓存。如果 SIZE 为 0，则禁用磁盘缓存。此功能在内存中缓存下载的数据，最多增长到 SIZE 字节。缓存存储为 aria2 实例创建，供所有下载共享使用。磁盘缓存的一个优点是减少磁盘 I/O，因为数据以较大的单位写入，并且按文件的偏移进行重新排序。如果涉及哈希检查且数据缓存在内存中，则无需从磁盘读取数据。SIZE 可以包括 K 或 M``（1K = 1024，1M = 1024K）。默认值为 ``16M

--download-result=<OPT>¶: 此选项更改格式化“下载结果”的方式。如果 OPT 为 default，打印 GID、状态、平均下载速度和路径/URI。如果涉及多个文件，则只打印第一个请求的文件的路径/URI，其余文件被省略。如果 OPT 为 full，打印 GID、状态、平均下载速度、进度百分比和路径/URI。每行都为每个请求的文件打印进度百分比和路径/URI。如果 OPT 为 hide，则隐藏“下载结果”。默认值为 default

--dscp=<DSCP>¶: 为 BitTorrent 流量中的传出 IP 数据包设置 DSCP 值以进行 QoS。此参数仅设置 IP 数据包的 TOS 字段中的 DSCP 位，而不是整个字段。如果您从 /usr/include/netinet/ip.h 获取值，请将它们除以 4（否则值将不正确，例如，您的 CS1 类将变为 CS4）。如果您从 RFC、网络供应商的文档、Wikipedia 或其他任何来源获取常用值，请直接使用它们。

--rlimit-nofile=<NUM>¶

设置打开文件描述符的软限制。仅当以下情况：

系统支持（posix）

限制没有超过硬限制。

指定的限制大于当前的软限制。

这相当于通过 ulimit 设置 nofile，但不会减小限制。

此选项仅适用于支持 rlimit API 的系统。

--enable-color [true|false]¶: 为终端启用彩色输出。默认值: true

--enable-mmap [true|false]¶

将文件映射到内存。如果文件空间没有预先分配，则此选项可能无法工作。参见 --file-allocation。

默认值: false

--event-poll=<POLL>¶: 指定轮询事件的方法。可能的值包括 epoll，kqueue，port，poll 和 select。对于每个 epoll，kqueue，port 和 poll，如果系统支持，则可用。epoll 可用于最新的 Linux。kqueue 可用于包括 Mac OS X 在内的各种 BSD 系统。port 可用于 Open Solaris。默认值可能因使用的系统而异。

--file-allocation=<METHOD>¶

指定文件分配方法。 none 不预先分配文件空间。prealloc 在下载开始之前预先分配文件空间。这可能需要一些时间，具体取决于文件的大小。如果您使用新的文件系统，如支持 extents 的 ext4，btrfs，xfs 或 NTFS（仅适用于 MinGW 构建），则 falloc 是您的最佳选择。它几乎立即分配大型（几GB）的文件。不要在诸如 ext3 和 FAT32 等旧文件系统上使用 falloc，因为它花费的时间几乎与 prealloc 一样长，并且会完全阻塞 aria2，直到分配完成。如果您的系统没有 posix_fallocate(3) 函数，则可能无法使用 falloc。 trunc 使用 ftruncate(2) 系统调用或特定于平台的相应项将文件截断到指定的长度。

可能的值: none，prealloc，trunc，falloc 默认值: prealloc

Warning

使用 trunc 看似非常快速地分配磁盘空间，但实际上它只是设置文件系统中的文件长度元数据，并没有实际分配磁盘空间。这意味着它无助于避免碎片化。

Note

在多文件种子下载中，与指定文件相邻的文件也会被分配，如果它们共享相同的片段。

--force-save [true|false]¶: 使用 --save-session 选项保存下载，即使下载已完成或已删除。在这些情况下，此选项还保存控制文件。这可能对保存被识别为已完成状态的 BitTorrent 种子非常有用。默认值: false

--save-not-found [true|false]¶: 使用 --save-session 选项保存下载，即使在服务器上未找到文件。在这些情况下，此选项也保存控制文件。默认值: true

--gid=<GID>¶: 手动设置 GID。aria2 通过称为 GID 的 ID 来识别每个下载。GID 必须是 16 个字符的十六进制字符串，因此允许包括 [0-9a-fA-F]，并且不能去掉前导零。GID 全部为 0 的保留，不得使用。GID 必须是唯一的，否则会报告错误并且不会添加下载。当使用 --save-session 选项恢复保存的会话时，此选项非常有用。如果不使用此选项，则 aria2 会生成新的 GID。

--hash-check-only [true|false]¶: 如果给出 true，在使用 --check-integrity 选项进行哈希检查后，无论下载是否完成，都会中止下载。默认值: false

--human-readable [true|false]¶: 在控制台输出中以人类可读的格式打印大小和速度（例如，1.2Ki，3.4Mi）。默认值: true

--interface=<INTERFACE>¶: 将套接字绑定到指定的接口。您可以指定接口名称、IP 地址和主机名。可能的值: 接口，IP 地址，主机名

Note

如果一个接口有多个地址，强烈建议明确指定 IP 地址。另请参阅 --disable-ipv6。如果系统没有 getifaddrs(3)，则此选项不接受接口名称。

--keep-unfinished-download-result [true|false]¶: 即使这样超过了 --max-download-result，也保留未完成的下载结果。如果所有未完成的下载都必须在会话文件中保存（请参见 --save-session 选项），这很有用。请记住，对要保留的未完成下载结果的数量没有上限。如果这不合适，关闭此选项。默认值: true

--max-download-result=<NUM>¶: 设置在内存中保留的最大下载结果数。下载结果包括已完成/错误/已删除的下载。下载结果存储在 FIFO 队列中，最多可存储 NUM 个下载结果。当队列已满并创建新的下载结果时，将从队列前端删除最旧的下载结果，并将新的下载结果推送到队列后端。在进行成千上万次下载后，为此选项指定较大的数字可能导致内存消耗太高。指定 0 表示不保留下载结果。请注意，不管此选项的值如何，未完成的下载都会保留在内存中。请参阅 --keep-unfinished-download-result 选项。默认值: 1000

--max-mmap-limit=<SIZE>¶: 设置启用 mmap 的最大文件大小（请参阅 --enable-mmap 选项）。文件大小由一个下载中包含的所有文件的总和确定。例如，如果一个下载包含 5 个文件，则文件大小是这些文件的总大小。如果文件大小严格大于此选项中指定的大小，则将禁用 mmap。默认值: 9223372036854775807

--max-resume-failure-tries=<N>¶: 当与 --always-resume=false, 一起使用时，当 aria2 检测到 N 个不支持恢复的 URI 时，从头开始下载文件。如果 N 为 0，则当所有给定的 URI 都不支持恢复时，aria2 从头开始下载文件。请参阅 --always-resume 选项。默认值: 0

--min-tls-version=<VERSION>¶: 指定要启用的最低 SSL/TLS 版本。可能的值: TLSv1.1，TLSv1.2，TLSv1.3 默认值: TLSv1.2

--multiple-interface=<INTERFACES>¶: 逗号分隔的接口列表，用于绑定套接字。请求将分散在接口之间以实现链路聚合。您可以指定接口名称、IP 地址和主机名。如果使用了 --interface，则此选项将被忽略。可能的值：接口、IP 地址、主机名

--log-level=<LEVEL>¶: 设置要输出的日志级别。 LEVEL 可以是 debug、info、notice、warn 或 error。默认值：debug

--on-bt-download-complete=<COMMAND>¶: 对于 BitTorrent，会在下载完成并停止种子时调用 --on-download-complete 中指定的命令。另一方面，此选项设置了在下载完成后但在种子之前执行的命令。有关 COMMAND 的更多详细信息，请参阅事件钩子。可能的值：/path/to/command

--on-download-complete=<COMMAND>¶: 设置在下载完成后要执行的命令。有关 COMMAND 的更多详细信息，请参阅事件钩子。还请参阅 --on-download-stop 选项。可能的值：/path/to/command

--on-download-error=<COMMAND>¶: 设置在因错误而中止下载后要执行的命令。有关 COMMAND 的更多详细信息，请参阅事件钩子。还请参阅 --on-download-stop 选项。可能的值：/path/to/command

--on-download-pause=<COMMAND>¶: 设置在下载暂停后要执行的命令。有关 COMMAND 的更多详细信息，请参阅事件钩子。可能的值：/path/to/command

--on-download-start=<COMMAND>¶: 设置在下载开始后要执行的命令。有关 COMMAND 的更多详细信息，请参阅事件钩子。可能的值：/path/to/command

--on-download-stop=<COMMAND>¶: 设置在下载停止后要执行的命令。您可以使用 --on-download-complete 和 --on-download-error 覆盖要执行的特定下载结果的命令。如果它们已指定，则不会执行此选项中指定的命令。有关 COMMAND 的更多详细信息，请参阅事件钩子。可能的值：/path/to/command

--optimize-concurrent-downloads [true|false|<A>:<B>]¶: 根据可用带宽优化并发下载的数量。aria2 使用先前下载时观察到的下载速度，根据规则 N = A + B Log10(speed in Mbps) 来调整启动的并行下载数量。可以使用选项参数中的 A 和 B 来自定义系数 A 和 B，它们由冒号分隔。默认值 (A=5, B=25) 通常在 1Mbps 及以上网络上使用 5 个并行下载，在 100Mbps 及以上网络上使用 50 个以上。并行下载数量保持在 --max-concurrent-downloads 参数定义的最大数量下。默认值：false

--piece-length=<LENGTH>¶: 为 HTTP/FTP 下载设置分片长度。这是 aria2 拆分文件的边界。所有拆分都发生在此长度的倍数上。在 BitTorrent 下载中，此选项将被忽略。如果 Metalink 文件包含片段哈希值，它也将被忽略。默认值：1M

Note

--piece-length 选项的可能用例是改变一个 HTTP 流水线请求中的请求范围。要启用 HTTP 流水线，请使用 --enable-http-pipelining。

--show-console-readout [true|false]¶: 显示控制台读取输出。默认值：true

--stderr [true|false]¶: 将所有本来会打印在标准输出中的控制台输出重定向到标准错误输出。默认值：false

--summary-interval=<SEC>¶: 设置以秒为单位的输出下载进度摘要的间隔。设置为 0 将抑制输出。默认值：60

-Z, --force-sequential [true|false]¶: 顺序获取命令行中的 URIs，并在单独的会话中下载每个 URI，就像通常的命令行下载工具一样。默认值：false

--max-overall-download-limit=<SPEED>¶: 设置最大的整体下载速度（以字节/秒为单位）。0 表示不受限制。您可以附加 K 或 M``（1K = 1024，1M = 1024K）。要限制每个下载的下载速度，请使用 :option:`--max-download-limit` 选项。默认值：``0

--max-download-limit=<SPEED>¶: 设置每个下载的最大下载速度（以字节/秒为单位）。0 表示不受限制。您可以附加 K 或 M``（1K = 1024，1M = 1024K）。要限制整体下载速度，请使用 :option:`--max-overall-download-limit` 选项。默认值：``0

--no-conf [true|false]¶: 禁用加载 aria2.conf 文件。

--no-file-allocation-limit=<SIZE>¶: 对于大小小于 SIZE 的文件，不进行文件分配。您可以附加 K 或 M``（1K = 1024，1M = 1024K）。默认值：``5M

-P, --parameterized-uri [true|false]¶: 启用参数化 URI 支持。您可以指定一组部分：http://{sv1,sv2,sv3}/foo.iso。也可以指定具有步进计数器的数字序列：http://host/image[000-100:2].img。步进计数器可以省略。如果所有的 URIs 指向不同的文件，例如上面的第二个示例，需要 -Z 选项。默认值：false

-q, --quiet [true|false]¶: 使 aria2 保持安静（无控制台输出）。默认值：false

--realtime-chunk-checksum [true|false]¶: 如果提供了块校验和，通过在下载文件时计算校验和来验证数据块。默认值：true

--remove-control-file [true|false]¶: 在下载之前移除控制文件。与 --allow-overwrite= 一起使用，下载总是从头开始。这对于那些无法恢复的代理服务器用户很有用。

--save-session=<FILE>¶

在退出时将错误/未完成的下载保存到 FILE 中。您可以通过 --input-file 选项将此输出文件传递给 aria2c 以在重新启动时使用。如果您希望输出为 gzip 格式，请在文件名后附加 .gz 扩展名。请注意，通过 aria2.addTorrent() 和 aria2.addMetalink() RPC 方法添加的无法保存为文件的下载元数据不会被保存。使用 aria2.remove() 和 aria2.forceRemove() 删除的下载将不会被保存。GID 也通过 gid 被保存，但有一些限制，请参见下文。

Note

通常情况下，会保存下载本身的 GID。但是一些下载使用了元数据（例如 BitTorrent 和 Metalink）。在这种情况下，有一些限制。

磁力链接，并跟随着 torrent 下载: 保存了 BitTorrent 元数据下载的 GID。
指向 torrent 文件的 URI，并跟随着 torrent 下载: 保存了 torrent 文件下载的 GID。
指向 metalink 文件的 URI，并跟随着 metalink 文件描述的文件下载: 保存了 metalink 文件下载的 GID。
本地 torrent 文件: 保存了 torrent 下载的 GID。
本地 metalink 文件: 未保存任何有意义的 GID。

--save-session-interval=<SEC>¶: 每隔 SEC 秒将错误/未完成的下载保存到 --save-session 选项指定的文件中。如果给定``0``，则文件只会在 aria2 退出时保存。默认值：0

--socket-recv-buffer-size=<SIZE>¶: 设置套接字接收缓冲区的最大字节数。指定``0``将禁用此选项。此值将使用 SO_RCVBUF 套接字选项和 setsockopt() 调用设置为套接字文件描述符。默认值：0

--stop=<SEC>¶: 在 SEC 秒后停止应用程序。如果给定``0``，则禁用此功能。默认值：0

--stop-with-process=<PID>¶: 在进程 PID 不运行时停止应用程序。如果 aria2 进程是从父进程分叉出来的，则这很有用。父进程可以使用自己的 pid 分叉 aria2，当父进程由于某种原因退出时，aria2 可以检测到并关闭自身。

--truncate-console-readout [true|false]¶: 截断控制台输出以适合单行显示。默认值：true

-v, --version¶: 打印版本号、版权信息和配置信息，然后退出。

选项注意事项¶

可选参数¶

其参数被方括号([])括起来的选项将具有可选参数。通常省略参数将被评估为``true``。如果使用这些选项的短格式（如``-V``）并给出参数，那么选项名称和其参数应连接在一起（例如``-Vfalse``）。如果在选项名称和参数之间插入任何空格，则参数将被视为 URI，并且通常这不是您期望的结果。

单位（K 和 M）¶

某些选项接受 K 和 M 以便方便地表示 1024 和 1048576。aria2 以大小写不敏感的方式检测这些字符。换句话说，分别可以使用 k 和 m 以及 K 和 M。

URI, 磁力链接, 种子文件, MetaLink 文件¶

你可以在命令行中指定多个URI。除非你使用了 --force-sequential 选项，否则所有的URI必须指向同一个文件，否则下载将会失败。你可以指定任意数量的BitTorrent磁力链接。请注意它们被始终视为单独的下载。支持使用16位进制编码的40个字符的Info Hash和Base32编码的32个字符的Info Hash。多个``tr``参数都是被支持的。因为BitTorrent磁力链接很可能包含``&``字符，强烈建议始终使用单引号（'）或双引号（"）引用URI。特别值得推荐的是在``tr``参数缺失时启用DHT。关于BitTorrent磁力链接的更多细节请参考http://www.bittorrent.org/beps/bep_0009.html。

你也可以指定任意数量的种子文件和存储在本地磁盘上的MetaLink文档。请注意它们始终被视为单独的下载。支持Metalink4和Metalink版本3.0。

你可以同时使用``-T``选项指定种子文件和URI。通过这样做，你可以同时从种子网络和HTTP(S)/FTP/SFTP服务器下载文件，同时HTTP(S)/FTP/SFTP服务器上的数据会被上传到种子网络。对于单文件种子，URI可以是指向资源的完整URI，或者如果URI以/结尾，则种子文件中的名称会被添加。对于多文件种子，名称和路径会被添加以形成每个文件的URI。

Note

如果URI包含``&``或任何shell中具有特殊含义的字符，确保用单引号（'）或双引号（"）引用URI。

恢复下载¶

通常，你可以通过发出相同的命令（aria2c URI）来恢复传输，如果先前的传输是由aria2创建的。

如果先前的传输是由浏览器或wget类似的顺序下载管理器创建的，那么使用 --continue 选项来继续传输。

事件钩子¶

aria2提供了选项来在特定事件发生后指定任意命令。目前有以下选项： --on-bt-download-complete, --on-download-pause, --on-download-complete. --on-download-start, --on-download-error, --on-download-stop.

当指定的命令被执行时，aria2会传递3个参数。这些参数分别是：GID，文件数量和文件路径。对于HTTP、FTP和SFTP下载，通常文件数量为1。BitTorrent下载可能包含多个文件。如果文件数量大于1，文件路径是第一个文件的路径。换句话说，这是:func:aria2.getFiles RPC方法响应中第一个selected键为true的struct的path键的值。如果你想获取所有文件路径，考虑使用JSON-RPC/XML-RPC。请注意，在HTTP下载中文件路径可能会因为重定向或Content-Disposition标头的原因在下载过程中发生变化。

让我们看一个示例，说明了如何将参数传递给命令：

$ cat hook.sh
#!/bin/sh
echo "Called with [$1] [$2] [$3]"
$ aria2c --on-download-complete hook.sh http://example.org/file.iso
Called with [1] [1] [/path/to/file.iso]

退出状态¶

因为aria2可以同时处理多个下载，所以在一个会话中遇到了很多错误。aria2基于最后一个遇到的错误返回以下退出状态。

0: 如果所有下载都成功了。
1: 如果发生了未知错误。
2: 如果发生了超时。
3: 如果未找到资源。
4: 如果aria2看到指定数量的“未找到资源”错误。参见 --max-file-not-found 选项。
5: 如果由于下载速度太慢而导致下载中止。参见 --lowest-speed-limit 选项。
6: 如果发生了网络问题。
7: 如果有未完成的下载。只有在所有完成的下载都成功且在用户通过按下 Ctrl-C 或发送TERM或INT信号退出aria2时，存在未完成的下载队列才会报告此错误。
8: 如果远程服务器不支持必须完成下载的恢复。
9: 如果没有足够的磁盘空间。
10: 如果分片长度与.aria2控制文件中的分片长度不同。参见 --allow-piece-length-change 选项。
11: 如果aria2在那个时刻正在下载相同的文件。
12: 如果aria2在那个时刻正在下载相同的info hash种子。
13: 如果文件已经存在。参见 --allow-overwrite 选项。
14: 如果重命名文件失败。参见 --auto-file-renaming 选项。
15: 如果aria2无法打开现有文件。
16: 如果aria2无法创建新文件或截断现有文件。
17: 如果发生文件I/O错误。
18: 如果aria2无法创建目录。
19: 如果名字解析失败。
20: 如果aria2无法解析MetaLink文档。
21: 如果FTP命令失败。
22: 如果HTTP响应标头不好或不符合预期。
23: 如果发生了太多的重定向。
24: 如果HTTP授权失败。
25: 如果aria2无法解析b编码文件（通常为“.torrent”文件）。
26: 如果“.torrent”文件损坏或缺少aria2需要的信息。
27: 如果磁力链接不好。
28: 如果给出了坏/无法识别的选项或给出了意外的选项参数。
29: 如果远程服务器由于临时超载或维护而无法处理请求。
30: 如果aria2无法解析JSON-RPC请求。
31: 保留。未使用。
32: 如果校验失败。

Note

已完成的下载中发生的错误不会报告为退出状态。

环境¶

aria2 可识别以下环境变量。

http_proxy [http://][USER:PASSWORD@]HOST[:PORT]: 指定用于 HTTP 的代理服务器。覆盖配置文件中的 http-proxy 值。命令行选项 --http-proxy 覆盖此值。
https_proxy [http://][USER:PASSWORD@]HOST[:PORT]: 指定用于 HTTPS 的代理服务器。覆盖配置文件中的 https-proxy 值。命令行选项 --https-proxy 覆盖此值。
ftp_proxy [http://][USER:PASSWORD@]HOST[:PORT]: 指定用于 FTP 的代理服务器。覆盖配置文件中的 ftp-proxy 值。命令行选项 --ftp-proxy 覆盖此值。
all_proxy [http://][USER:PASSWORD@]HOST[:PORT]: 指定在未指定特定协议代理时使用的代理服务器。覆盖配置文件中的 all-proxy 值。命令行选项 --all-proxy 覆盖此值。

Note

虽然 aria2 接受代理 URI 中的 ftp:// 和 https:// 方案，但它假定只指定了 http://，并且不会基于指定的方案来改变其行为。

no_proxy [DOMAIN,...]: 指定逗号分隔的主机名、域和网络地址（带或不带子网掩码）列表，不使用任何代理。覆盖配置文件中的 no-proxy 值。命令行选项 --no-proxy 覆盖此值。

文件¶

aria2.conf¶

默认情况下，aria2 会检查传统路径``$HOME/.aria2/aria2.conf`` 是否存在，否则解析``$XDG_CONFIG_HOME/aria2/aria2.conf`` 作为配置文件。您可以使用 --conf-path 选项指定配置文件的路径。如果不想使用配置文件，使用 --no-conf 选项。

配置文件是一个文本文件，每行有一个选项。在每一行中，您可以按照格式``NAME=VALUE``，指定名称-值对，其中名称是长命令行选项的名称，不带``–前缀。您可以对命令行选项使用相同的语法。以 ``# 开头的行被视为注释:

# aria2c 的示例配置文件
listen-port=60000
dht-listen-port=60000
seed-ratio=1.0
max-upload-limit=50K
ftp-pasv=true

Note

配置文件中可能包含例如用户名/密码之类的机密信息。建议更改配置文件的文件模式位（例如 chmod 600 aria2.conf），这样其他用户就无法看到文件的内容。

环境变量，例如``${HOME}``，会被 shell 展开。这意味着配置文件中使用的这些变量不会被展开。然而，在配置文件中使用``${HOME}``来指定文件路径，是有用的。因此，aria2 会将以下选项值中的``${HOME}``展开为用户的主目录：

请注意，即使上述选项在命令行中使用，此展开也会发生。这意味着展开可能会发生 2 次：首先是 shell，然后是 aria2c。

dht.dat¶

除非传统文件路径``$HOME/.aria2/dht.dat`` 和``$HOME/.aria2/dht6.dat`` 指向现有文件，否则 IPv4 DHT 的路由表将保存到路径``$XDG_CACHE_HOME/aria2/dht.dat``，并将 IPv6 DHT 的路由表保存到路径``$XDG_CACHE_HOME/aria2/dht6.dat``。

Netrc¶

默认情况下，启用了 HTTP(S)/FTP/SFTP 的 netrc 支持。要禁用 netrc 支持，请指定 --no-netrc 选项。您的 .netrc 文件应具有正确的权限（600）。

如果机器名称以``.``开头，aria2 执行域匹配而不是精确匹配。这是 aria2 的扩展。域匹配示例：假设有以下 .netrc 条目的域匹配示例:

machine .example.org login myid password mypasswd

aria2.example.org 域匹配``.example.org``，并使用``myid``和``mypasswd``。

一些域匹配示例如下：example.net 不会域匹配``.example.org``。example.org 不会域匹配``.example.org``，因为有前面的``.``。如果要匹配``example.org``，请指定``example.org``。

控制文件¶

aria2 使用控制文件跟踪下载的进展。控制文件放在与正在下载的文件相同的目录中，其文件名是正在下载的文件名加上``.aria2``。例如，如果您正在下载 file.zip，那么控制文件应为 file.zip.aria2。（对于此命名约定有一项例外。如果您正在下载多个种子包，则其控制文件是种子文件中“info”目录中“name”键的“顶级目录”名称，末尾添加``.aria2``。）

通常，下载完成后会删除控制文件。如果 aria2 决定无法恢复下载（例如，从不支持续传的 HTTP 服务器下载文件时），则不会创建控制文件。

通常情况下，如果丢失控制文件，则无法继续下载。但是，如果您有包含文件块校验和的种子或者 metalink，您可以在命令行中给 aria2c 传递 -V 选项，这样即使没有控制文件，也可以恢复下载。

输入文件¶

输入文件可以包含 aria2 下载的 URI 列表。您可以为单个实体指定多个 URI：使用 TAB 字符在单行上分隔 URI。

每行都被视为以命令行参数提供。因此，它们受到 --force-sequential 和 --parameterized-uri 选项的影响。

由于输入文件中的 URI 是由 aria2 直接读取的，因此不得用单引号（'）或双引号（"）引起来。

以 # 开头的行被视为注释并被跳过。

此外，在每行 URI 后面可以指定以下选项。这些可选行必须以空格开头。

这些选项与命令行选项的含义完全相同，但仅适用于其所属的 URI。请注意，对于输入文件中的选项，-- 前缀必须被删除。

例如，uri.txt 的内容如下:

http://server/file.iso http://mirror/file.iso
  dir=/iso_images
  out=file.img
http://foo/bar

如果使用 -i uri.txt -d /tmp 选项执行 aria2，那么 file.iso 将保存为 /iso_images/file.img，并且从``http://server/file.iso`` 和``http://mirror/file.iso`` 下载。文件 bar 将从``http://foo/bar`` 下载，并保存为``/tmp/bar``。

在某些情况下，out 参数没有效果。请参见 --out 选项的说明。

服务器性能配置文件¶

本节描述了服务器性能配置文件的格式。该文件是纯文本，每一行都有几对``NAME=VALUE``，用逗号分隔。当前识别以下名字：

host: 服务器的主机名。必填。
protocol: 此配置文件的协议，例如 ftp、http。必填。
dl_speed: 上次下载时观察到的平均下载速度，以每秒字节为单位。必填。
sc_avg_speed: 上次下载时观察到的单连接环境中的平均下载速度，以每秒字节为单位。如果下载在单连接环境中完成，这个值才会被更新，只会被``AdaptiveURISelector``使用。可选。
mc_avg_speed: 上次下载时观察到的多连接环境中的平均下载速度，以每秒字节为单位。如果下载在多连接环境中完成，这个值才会被更新，只会被``AdaptiveURISelector``使用。可选。
counter: 服务器被使用的次数。目前此值仅被``AdaptiveURISelector``使用。可选。
last_updated: 与该服务器的最后一次联系时间，用自 1970 年 1 月 1 日 00:00:00 UTC 以来的秒数来指定。必填。
status: 当服务器无法访问、处于脱机状态或发生超时时会设置为ERROR。否则，会设置为OK。

这些字段必须在同一行存在。字段的顺序并不重要。你可以放置除以上之外的键值对；它们会被简单地忽略。

以下是一个示例：

host=localhost, protocol=http, dl_speed=32000, last_updated=1222491640, status=OK
host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR

RPC 接口¶

aria2 提供 JSON-RPC over HTTP 和 XML-RPC over HTTP 接口，它们基本上提供相同的功能。aria2 还提供 JSON-RPC over WebSocket。JSON-RPC over WebSocket 使用与 JSON-RPC over HTTP 相同的方法签名和响应格式，但另外还提供了服务器发起的通知。有关更多信息，请参阅 JSON-RPC over WebSocket 部分。

JSON-RPC 接口的请求路径（对于 HTTP 和 WebSocket）是 /jsonrpc。XML-RPC 接口的请求路径是 /rpc。

JSON-RPC over WebSocket 的 WebSocket URI 是 ws://HOST:PORT/jsonrpc。如果启用了 SSL/TLS 加密，请改用 wss://HOST:PORT/jsonrpc。

实现的 JSON-RPC 基于 JSON-RPC 2.0 <http://jsonrpc.org/specification>，并支持 HTTP POST 和 GET（JSONP）。WebSocket 传输是 aria2 的扩展。

JSON-RPC 接口不支持通过 HTTP 发送通知，但 RPC 服务器将会通过 WebSocket 发送通知。它也不支持浮点数。字符编码必须是 UTF-8。

在阅读 JSON-RPC 的以下文档时，将结构理解为 JSON 对象。

术语¶

GID

GID（或 gid）是管理每个下载的关键。每个下载都会被分配一个唯一的 GID。GID 在 aria2 中以 64 位二进制值的形式存储。对于 RPC 访问，它以 16 个字符的十六进制字符串表示（例如，2089b05ecca3d829）。通常，aria2 为每个下载生成这个 GID，但用户可以使用 --gid 选项手动指定 GID。在通过 GID 查询下载时，只要该前缀在其他 GID 中是唯一的，你可以只指定 GID 的前缀。

RPC 授权秘密令牌¶

从 1.18.4 版本开始，除了 HTTP 基本授权之外，aria2 还提供了 RPC 方法级别的授权。在将来的版本中，HTTP 基本授权将被移除，RPC 方法级别的授权将变得强制性。

要使用 RPC 方法级别的授权，用户必须使用 --rpc-secret 选项指定一个 RPC 秘密授权令牌。对于每个 RPC 方法调用，调用者必须在令牌前加上 token:。即使没有使用 --rpc-secret 选项，如果 RPC 方法中的第一个参数是以 token: 开头的字符串，它将在请求处理之前从参数列表中移除。

例如，如果 RPC 秘密授权令牌是 $$secret$$，调用 aria2.addUri RPC 方法将如下所示:

aria2.addUri("token:$$secret$$", ["http://example.org/file"])

system.multicall RPC 方法被特殊对待。由于 XML-RPC 规范只允许将单个数组作为此方法的参数，我们不在调用中指定令牌。相反，每个嵌套方法调用都必须像上面描述的那样提供令牌作为第一个参数。

Note

aria2 中的秘密令牌验证被设计为至少需要一定时间来减轻对 RPC 接口的暴力破解/字典攻击。因此建议在合适的情况下优先使用批量或 system.multicall 请求。

system.listMethods 和 system.listNotifications 可以在没有令牌的情况下执行。由于它们只是返回可用的方法/通知，它们不会改变任何东西，所以在没有秘密令牌的情况下是安全的。

方法¶

所有代码示例都兼容 Python 2.7 解释器。关于 secret 参数的信息，请参阅 RPC 授权秘密令牌。

aria2.addUri([secret, ]uris[, options[, position]])¶

此方法添加新下载。uris 是指向同一资源的 HTTP/FTP/SFTP/BitTorrent URI（字符串）数组。如果混合使用指向不同资源的 URI，则下载可能会失败或在 aria2 不报错的情况下发生损坏。添加 BitTorrent Magnet URI 时，uris 必须只有一个元素，且应为 BitTorrent Magnet URI。options 是结构体，其成员是选项名称和值的对。有关更多详细信息，请参阅下面的选项。如果给出 position，它必须是一个从 0 开始的整数。新下载将在等待队列中的 position 处插入。如果省略了 position 或 position 大于队列的当前大小，则新下载将附加到队列的末尾。此方法返回新注册下载的 GID。

JSON-RPC 示例

以下示例添加 http://example.org/file:

>>> import urllib2, json
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.addUri',
...                       'params':[['http://example.org/file']]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> c.read()
'{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'

XML-RPC 示例

以下示例添加 http://example.org/file:

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.addUri(['http://example.org/file'])
'2089b05ecca3d829'

以下示例添加两个来源和一些选项的新下载:

>>> s.aria2.addUri(['http://example.org/file', 'http://mirror/file'],
                    dict(dir="/tmp"))
'd2703803b52216d1'

以下示例添加下载并将其插入到队列的开头处:

>>> s.aria2.addUri(['http://example.org/file'], {}, 0)
'ca3d829cee549a4d'

aria2.addTorrent([secret, ]torrent[, uris[, options[, position]]])¶

此方法通过上传 “.torrent” 文件添加 BitTorrent 下载。如果要添加 BitTorrent Magnet URI，请改用 aria2.addUri() 方法。torrent 必须是包含 “.torrent” 文件内容的 base64 编码字符串。uris 是 URI（字符串）的数组。uris 用于 Web-seeding。对于单个文件种子，URI 可以是指向资源的完整 URI；如果 URI 以 / 结尾，则将种子文件中的名称添加。对于多文件种子，将种子中的名称和路径添加以形成每个文件的 URI。options 是结构体，其成员是选项名称和值的对。有关更多详细信息，请参阅下面的选项。如果给出 position，它必须是一个从 0 开始的整数。新下载将在等待队列中的 position 处插入。如果省略了 position 或 position 大于队列的当前大小，则新下载将附加到队列的末尾。此方法返回新注册下载的 GID。如果 --rpc-save-upload-metadata 为``true``，上传的数据将保存为以数据 SHA-1 哈希的十六进制字符串加上 “.torrent” 作为文件名，保存在 --dir 选项指定的目录中。例如，文件名可能是``0a3893293e27ac0490424c06de4d09242215f0a6.torrent``。如果同名文件已存在，它将被覆盖！如果无法成功保存文件或 --rpc-save-upload-metadata 为``false``，此方法添加的下载将不会被 --save-session 保存。

以下示例添加本地文件 file.torrent。

JSON-RPC 示例

>>> import urllib2, json, base64
>>> torrent = base64.b64encode(open('file.torrent').read())
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'asdf',
...                       'method':'aria2.addTorrent', 'params':[torrent]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> c.read()
'{"id":"asdf","jsonrpc":"2.0","result":"2089b05ecca3d829"}'

XML-RPC 示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
'2089b05ecca3d829'

aria2.addMetalink([secret, ]metalink[, options[, position]])¶

该方法通过上传“.metalink”文件以添加 Metalink 下载。 metalink 是一个 Base64 编码的字符串，其中包含“.metalink”文件的内容。 options 是一个结构体，其成员是选项名称和值的对。查看下面的选项以获取更多详细信息。如果给定 position，它必须是一个从 0 开始的整数。新下载将被插入到等待队列中的 position。如果省略 position 或者 position 大于当前队列的大小，则新的下载将被追加到队列末尾。该方法返回新注册下载的 GIDs 数组。如果 --rpc-save-upload-metadata 为 true，则上传的数据将被保存为命名为数据的 SHA-1 哈希的十六进制字符串加上“.metalink”后缀的文件，并保存在 --dir 选项指定的目录中。例如，文件名可能是 0a3893293e27ac0490424c06de4d09242215f0a6.metalink。如果同名文件已存在，则该文件将被覆盖！如果无法成功保存文件或 --rpc-save-upload-metadata 为 false，通过该方法添加的下载将不会被 --save-session 保存。

下面的示例添加本地文件 file.meta4。

JSON-RPC 示例

>>> import urllib2, json, base64
>>> metalink = base64.b64encode(open('file.meta4').read())
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.addMetalink',
...                       'params':[metalink]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> c.read()
'{"id":"qwer","jsonrpc":"2.0","result":["2089b05ecca3d829"]}'

XML-RPC 示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.addMetalink(xmlrpclib.Binary(open('file.meta4', mode='rb').read()))
['2089b05ecca3d829']

aria2.remove([secret, ]gid)¶

该方法移除由 *gid*（字符串）表示的下载。如果指定的下载正在进行中，则首先将其停止。移除的下载状态将变为“removed”。该方法返回已移除下载的 GID。

下面的示例删除 GID 为 #2089b05ecca3d829 的下载。

JSON-RPC 示例

>>> import urllib2, json
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.remove',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> c.read()
'{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'

XML-RPC 示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.remove('2089b05ecca3d829')
'2089b05ecca3d829'

aria2.forceRemove([secret, ]gid)¶: 该方法移除由 gid 表示的下载。该方法的行为与 aria2.remove() 相同，只是该方法在不执行任何需要时间的操作的情况下移除下载，例如首先联系 BitTorrent 跟踪器取消注册下载。

aria2.pause([secret, ]gid)¶: 该方法暂停由 *gid*（字符串）表示的下载。暂停的下载状态变为“paused”。如果下载处于活动状态，则将其放在等待队列的前面。在状态为“paused”时，下载将不会启动。要将状态更改为“waiting”，请使用 aria2.unpause() 方法。该方法返回已暂停下载的 GID。

aria2.pauseAll([secret])¶: 该方法等同于为每个活动/等待下载调用 aria2.pause()。该方法返回“OK”。

aria2.forcePause([secret, ]gid)¶: 该方法暂停由 gid 表示的下载。该方法的行为与 aria2.pause() 相同，只是该方法在不执行任何需要时间的操作的情况下暂停下载，例如首先联系 BitTorrent 跟踪器取消注册下载。

aria2.forcePauseAll([secret])¶: 该方法等同于为每个活动/等待下载调用 aria2.forcePause()。该方法返回“OK”。

aria2.unpause([secret, ]gid)¶: 该方法将由 *gid*（字符串）表示的下载的状态从“paused”更改为“waiting”，使得下载有资格重新启动。该方法返回已取消暂停下载的 GID。

aria2.unpauseAll([secret])¶: 该方法等同于为每个已暂停下载调用 aria2.unpause()。该方法返回“OK”。

aria2.tellStatus([secret, ]gid[, keys])¶

此方法返回由 gid*（字符串）表示的下载的进度。*keys 是一个字符串数组。如果指定了 keys，响应将只包含 keys 数组中的键。如果 keys 为空或省略，则响应将包含所有的键。这在你只想要特定键并避免不必要的传输时非常有用。例如，aria2.tellStatus("2089b05ecca3d829", ["gid", "status"]) 仅返回 gid 和 status 键。响应是一个结构，包含以下键。值均为字符串。

gid

下载的 GID。

status

active 表示当前正在下载/做种的下载。 waiting 表示在队列中的下载；下载尚未开始。 paused 表示暂停的下载。 error 表示因错误而停止的下载。 complete 表示停止并完成的下载。 removed 表示用户移除的下载。

totalLength

下载的总长度（以字节为单位）。

completedLength

下载的已完成长度（以字节为单位）。

uploadLength

上传的长度（以字节为单位）。

bitfield

下载进度的十六进制表示。最高位对应索引为 0 的片段。任何被设定的位表示已加载的片段，而未设置的位表示尚未加载和/或丢失的片段。末尾的任何溢出位被设定为零。当下载尚未开始时，此键不会包含在响应中。

downloadSpeed

此下载的下载速度，以字节/秒为单位。

uploadSpeed

此下载的上传速度，以字节/秒为单位。

infoHash

InfoHash。仅适用于 BitTorrent。

numSeeders

aria2 连接的做种者数量。仅适用于 BitTorrent。

seeder

如果本地端点是做种者，则为“true”，否则为“false”。仅适用于 BitTorrent。

pieceLength

片段长度（以字节为单位）。

numPieces

片段数量。

connections

aria2 连接到的对等方/服务器数量。

errorCode

对于此项的最后一个错误代码，如果有的话。值为字符串。错误代码在退出状态部分中有定义。此值仅适用于已停止/已完成的下载。

errorMessage

与 errorCode 相关的（希望是）人类可读的错误消息。

followedBy

生成为此下载结果的 GID 列表。例如，当 aria2 下载一个 Metalink 文件时，会生成 Metalink 中描述的下载（参见 --follow-metalink 选项）。此值对于跟踪自动生成的下载非常有用。如果没有这样的下载，则此键不会包含在响应中。

following

“followedBy”的反向链接。包含在“followedBy”中的下载在其 following 值中具有该对象的 GID。

belongsTo

父下载的 GID。某些下载是另一个下载的一部分。例如，如果 Metalink 中的文件具有 BitTorrent 资源，则“.torrent”文件的下载是该父项的一部分。如果此下载没有父项，则此键不会包含在响应中。

dir

保存文件的目录。

files

返回文件列表。此列表的元素与 aria2.getFiles() 方法中使用的相同结构。

bittorrent

包含从 .torrent（文件）检索到的信息的结构。仅适用于 BitTorrent。包含以下键。

announceList

公告 URI 的列表列表。如果种子包含 announce 而不包含 announce-list，则将 announce 转换为 announce-list 格式。

comment

种子的注释。如果可用，则使用 comment.utf-8。

creationDate

种子的创建时间。该值是自纪元以来以秒为单位的整数。

mode

种子的文件模式。该值为“single”或“multi”。

info

包含来自 Info 字典的数据的结构。包含以下键。

name: info 字典中的名称。如果可用，则使用 “name.utf-8”。

verifiedLength

在文件进行哈希检查时验证的字节数量。此键仅在此下载正在进行哈希检查时存在。

verifyIntegrityPending

如果此下载正在等待在队列中进行哈希检查，则为“true”。此键仅在此下载在队列中时存在。

JSON-RPC 示例

以下示例获取了 GID＃2089b05ecca3d829 的下载信息：

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.tellStatus',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'bitfield': u'0000000000',
             u'completedLength': u'901120',
             u'connections': u'1',
             u'dir': u'/downloads',
             u'downloadSpeed': u'15158',
             u'files': [{u'index': u'1',
                         u'length': u'34896138',
                         u'completedLength': u'34896138',
                         u'path': u'/downloads/file',
                         u'selected': u'true',
                         u'uris': [{u'status': u'used',
                                    u'uri': u'http://example.org/file'}]}],
             u'gid': u'2089b05ecca3d829',
             u'numPieces': u'34',
             u'pieceLength': u'1048576',
             u'status': u'active',
             u'totalLength': u'34896138',
             u'uploadLength': u'0',
             u'uploadSpeed': u'0'}}

以下示例仅获取特定的键：

>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.tellStatus',
...                       'params':['2089b05ecca3d829',
...                                 ['gid',
...                                  'totalLength',
...                                  'completedLength']]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'completedLength': u'5701632',
             u'gid': u'2089b05ecca3d829',
             u'totalLength': u'34896138'}}

XML-RPC 示例

以下示例获取了 GID＃2089b05ecca3d829 的下载信息：

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.tellStatus('2089b05ecca3d829')
>>> pprint(r)
{'bitfield': 'ffff80',
 'completedLength': '34896138',
 'connections': '0',
 'dir': '/downloads',
 'downloadSpeed': '0',
 'errorCode': '0',
 'files': [{'index': '1',
            'length': '34896138',
            'completedLength': '34896138',
            'path': '/downloads/file',
            'selected': 'true',
            'uris': [{'status': 'used',
                      'uri': 'http://example.org/file'}]}],
 'gid': '2089b05ecca3d829',
 'numPieces': '17',
 'pieceLength': '2097152',
 'status': 'complete',
 'totalLength': '34896138',
 'uploadLength': '0',
 'uploadSpeed': '0'}

以下示例仅获取特定的键：

>>> r = s.aria2.tellStatus('2089b05ecca3d829', ['gid', 'totalLength', 'completedLength'])
>>> pprint(r)
{'completedLength': '34896138', 'gid': '2089b05ecca3d829', 'totalLength': '34896138'}

aria2.getUris([secret, ]gid)¶

该方法返回由 *gid*（字符串）指定的下载中使用的URIs。响应是一个包含以下键的结构数组。值为字符串。

uri: URI
status: 如果URI正在使用，则为’used’。如果URI仍在队列中等待，则为’waiting’。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getUris',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': [{u'status': u'used',
              u'uri': u'http://example.org/file'}]}

XML-RPC 示例

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getUris('2089b05ecca3d829')
>>> pprint(r)
[{'status': 'used', 'uri': 'http://example.org/file'}]

aria2.getFiles([secret, ]gid)¶

该方法返回由 *gid*（字符串）指定的下载的文件列表。响应是包含以下键的结构数组。值为字符串。

index: 文件的索引，从1开始，与多文件种子中文件的出现顺序相同。
path: 文件路径。
length: 文件大小（以字节为单位）。
completedLength: 此文件的已完成长度（以字节为单位）。请注意，completedLength 的总和可能小于 aria2.tellStatus() 方法返回的 completedLength。这是因为 aria2.getFiles() 中的 completedLength 仅包括已完成的片段。另一方面，aria2.tellStatus() 中的 completedLength 还包括部分完成的片段。
selected: 如果该文件被 --select-file 选项选择，则为“true”。如果未指定 --select-file 或者这是单文件种子或者根本不是种子下载，则该值始终为“true”。否则为“false”。
uris: 返回此文件的URI列表。元素类型与 aria2.getUris() 方法中使用的相同的结构相同。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getFiles',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': [{u'index': u'1',
              u'length': u'34896138',
              u'completedLength': u'34896138',
              u'path': u'/downloads/file',
              u'selected': u'true',
              u'uris': [{u'status': u'used',
                         u'uri': u'http://example.org/file'}]}]}

XML-RPC 示例

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getFiles('2089b05ecca3d829')
>>> pprint(r)
[{'index': '1',
  'length': '34896138',
  'completedLength': '34896138',
  'path': '/downloads/file',
  'selected': 'true',
  'uris': [{'status': 'used',
            'uri': 'http://example.org/file'}]}]

aria2.getPeers([secret, ]gid)¶

此方法返回由 *gid*（字符串）指定的下载的对等方列表。此方法仅适用于 BitTorrent。响应是一个结构数组，包含以下键。值为字符串。

peerId: 百分比编码的对等方 ID。
ip: 对等方的 IP 地址。
port: 对等方的端口号。
bitfield: 对等方下载进度的十六进制表示。最高位对应索引为 0 的片段。设置位表示该片段可用，未设置位表示该片段丢失。末尾的任何多余位都设置为零。
amChoking: 如果 aria2 限速对等方，则为 true。否则为 false。
peerChoking: 如果对等方限速 aria2，则为 true。否则为 false。
downloadSpeed: 该客户端从对等方获取的下载速度（字节/秒）。
uploadSpeed: 该客户端上传到对等方的上传速度（字节/秒）。
seeder: 如果此对等方是种子，则为 true。否则为 false。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getPeers',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': [{u'amChoking': u'true',
              u'bitfield': u'ffffffffffffffffffffffffffffffffffffffff',
              u'downloadSpeed': u'10602',
              u'ip': u'10.0.0.9',
              u'peerChoking': u'false',
              u'peerId': u'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
              u'port': u'6881',
              u'seeder': u'true',
              u'uploadSpeed': u'0'},
             {u'amChoking': u'false',
              u'bitfield': u'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
              u'downloadSpeed': u'8654',
              u'ip': u'10.0.0.30',
              u'peerChoking': u'false',
              u'peerId': u'bittorrent client758',
              u'port': u'37842',
              u'seeder': u'false',
              u'uploadSpeed': u'6890'}]}

XML-RPC 示例

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getPeers('2089b05ecca3d829')
>>> pprint(r)
[{'amChoking': 'true',
  'bitfield': 'ffffffffffffffffffffffffffffffffffffffff',
  'downloadSpeed': '10602',
  'ip': '10.0.0.9',
  'peerChoking': 'false',
  'peerId': 'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
  'port': '6881',
  'seeder': 'true',
  'uploadSpeed': '0'},
 {'amChoking': 'false',
  'bitfield': 'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
  'downloadSpeed': '8654',
  'ip': '10.0.0.30',
  'peerChoking': 'false',
  'peerId': 'bittorrent client758',
  'port': '37842',
  'seeder': 'false',
  'uploadSpeed': '6890'}]

aria2.getServers([secret, ]gid)¶

此方法返回当前连接的 HTTP(S)/FTP/SFTP 服务器列表，这些服务器用于由 *gid*（字符串）指定的下载。响应是一个结构数组，包含以下键。值为字符串。

index

文件的索引，从 1 开始，按照文件在多文件 Metalink 中出现的顺序排列。

servers

包含以下键的结构列表。

uri: 原始 URI。
currentUri: 这是当前用于下载的 URI。如果涉及重定向，currentUri 和 uri 可能不同。
downloadSpeed: 下载速度（字节/秒）

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getServers',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': [{u'index': u'1',
              u'servers': [{u'currentUri': u'http://example.org/file',
                            u'downloadSpeed': u'10467',
                            u'uri': u'http://example.org/file'}]}]}

XML-RPC 示例

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getServers('2089b05ecca3d829')
>>> pprint(r)
[{'index': '1',
  'servers': [{'currentUri': 'http://example.org/dl/file',
               'downloadSpeed': '20285',
               'uri': 'http://example.org/file'}]}]

aria2.tellActive([secret][, keys])¶: 此方法返回一个活动下载的列表。响应是与 aria2.tellStatus() 方法返回的相同结构的数组。对于 keys 参数，请参考 aria2.tellStatus() 方法。

aria2.tellWaiting([secret, ]offset, num[, keys])¶

该方法返回等待下载的列表，包括已暂停的下载。 offset 是一个整数，指定从等待队列前端的偏移量。 num 是一个整数，指定要返回的最大下载数量。对于 keys 参数，请参考 aria2.tellStatus() 方法。

如果 offset 是一个正整数，此方法返回范围 [offset, offset + num) 内的下载。

offset 可以是一个负整数。offset == -1 指向等待队列中的最后一个下载，offset == -2 指向倒数第二个下载，依此类推。此时响应中的下载顺序是反向的。

例如，假设有三个下载 “A”, “B” 和 “C” 按此顺序在等待。aria2.tellWaiting(0, 1) 返回 ["A"]。aria2.tellWaiting(1, 2) 返回 ["B", "C"]。aria2.tellWaiting(-1, 2) 返回 ["C", "B"]。

响应是一个数组，其结构与 aria2.tellStatus() 方法返回的结构相同。

aria2.tellStopped([secret, ]offset, num[, keys])¶

此方法返回一个停止下载的列表。 offset 是一个整数，指定了从最近停止的下载队列中的偏移量。 num 是一个整数，指定了要返回的最大下载数。对于 keys 参数，请参考 aria2.tellStatus() 方法。

offset 和 num 的语义与 aria2.tellWaiting() 方法中描述的相同。

响应是一个与 aria2.tellStatus() 方法返回的相同结构的数组。

aria2.changePosition([secret, ]gid, pos, how)¶

此方法更改由 gid 指示的下载在队列中的位置。 pos 是一个整数。 how 是一个字符串。如果 how 为 POS_SET，它将移动下载到相对于队列开头的位置。如果 how 为 POS_CUR，它将移动下载到相对于当前位置的位置。如果 how 为 POS_END，它将移动下载到相对于队列末尾的位置。如果目标位置小于 0 或超出队列的末尾，它会将下载分别移动到队列的开头或末尾。响应是表示结果位置的整数。

例如，如果 GID#2089b05ecca3d829 当前在位置 3， aria2.changePosition('2089b05ecca3d829', -1, 'POS_CUR') 将把其位置更改为 2。另外， aria2.changePosition('2089b05ecca3d829', 0, 'POS_SET') 将把其位置更改为 0（队列的开头）。

以下示例将下载 GID#2089b05ecca3d829 移动到队列的最前面。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.changePosition',
...                       'params':['2089b05ecca3d829', 0, 'POS_SET']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': 0}

XML-RPC 示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.changePosition('2089b05ecca3d829', 0, 'POS_SET')
0

aria2.changeUri([secret, ]gid, fileIndex, delUris, addUris[, position])¶

此方法会从 delUris 中删除 URI，并将 addUris 附加到由 gid 指示的下载中。delUris 和 addUris 是字符串列表。一个下载可能包含多个文件，并且 URI 附加到每个文件中。fileIndex 用于选择要删除/附加给定 URI 的文件。fileIndex 是基于 1 的。position 用于指定 URIs 要插入到现有等待 URI 列表中的位置。position 是基于 0 的。当省略 position 时，URIs 将附加到列表的末尾。此方法首先执行删除，然后执行添加。position 是在删除 URI 后的位置，而不是调用此方法时的位置。在删除 URI 时，如果下载中存在相同的 URI，则每个 delUris 中的 URI 仅移除一个。换句话说，如果有三个 URI http://example.org/aria2 并且想要全部移除它们，你必须在 delUris 中指定（至少）3 个 http://example.org/aria2。此方法返回一个包含两个整数的列表。第一个整数是删除的 URI 数量。第二个整数是添加的 URI 数量。

以下示例将 URI http://example.org/file 添加到索引为 1 的文件，并且属于下载 GID#2089b05ecca3d829 中。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.changeUri',
...                       'params':['2089b05ecca3d829', 1, [],
                                    ['http://example.org/file']]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [0, 1]}

XML-RPC 示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.changeUri('2089b05ecca3d829', 1, [],
                      ['http://example.org/file'])
[0, 1]

aria2.getOption([secret, ]gid)¶

此方法返回由 gid 指示的下载的选项。响应是一个结构，其中键是选项的名称。值是字符串。请注意，此方法不返回没有默认值并且未在命令行、配置文件或 RPC 方法中设置的选项。

以下示例获取下载 GID#2089b05ecca3d829 的选项。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getOption',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'allow-overwrite': u'false',
             u'allow-piece-length-change': u'false',
             u'always-resume': u'true',
             u'async-dns': u'true',
 ...

XML-RPC 示例

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getOption('2089b05ecca3d829')
>>> pprint(r)
{'allow-overwrite': 'false',
 'allow-piece-length-change': 'false',
 'always-resume': 'true',
 'async-dns': 'true',
 ....

aria2.changeOption([secret, ]gid, options)¶

此方法动态更改由 gid*（字符串）表示的下载的选项。 *options 是一个结构体。输入文件子部分列出了可用的选项，**除了**以下选项：

dry-run
metalink-base-uri
parameterized-uri
pause
piece-length
rpc-save-upload-metadata

除了以下选项之外，更改活动下载的其他选项会导致其重新启动（重新启动由 aria2 管理，无需用户干预）：

bt-max-peers
bt-request-peer-speed-limit
bt-remove-unselected-file
force-save
max-download-limit
max-upload-limit

此方法返回成功时为 OK。

以下示例将 max-download-limit 选项设置为 20K，用于下载 GID#2089b05ecca3d829。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.changeOption',
...                       'params':['2089b05ecca3d829',
...                                 {'max-download-limit':'10K'}]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'}

XML-RPC 示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.changeOption('2089b05ecca3d829', {'max-download-limit':'20K'})
'OK'

aria2.getGlobalOption([secret])¶: 此方法返回全局选项。响应是一个结构体。它的键是选项的名称。值是字符串。请注意，此方法不返回没有默认值且未在命令行、配置文件或 RPC 方法上设置的选项。由于全局选项用作新添加下载的选项模板，响应包含 aria2.getOption() 方法返回的键。

aria2.changeGlobalOption([secret, ]options)¶

此方法动态更改全局选项。 options 是一个结构体。以下选项可用：

bt-max-open-files
download-result
keep-unfinished-download-result
log
log-level
max-concurrent-downloads
max-download-result
max-overall-download-limit
max-overall-upload-limit
optimize-concurrent-downloads
save-cookies
save-session
server-stat-of

此外，输入文件子部分中列出的选项可用，**除了**以下选项： checksum, index-out, out, pause 和 select-file。

使用 log 选项，可以动态启动日志记录或更改日志文件。要停止记录日志，请将空字符串(“”)指定为参数值。请注意，日志文件始终以追加模式打开。此方法返回成功时为 OK。

aria2.getGlobalStat([secret])¶

此方法返回全局统计信息，例如总体下载和上传速度。响应是一个结构体，包含以下键。值为字符串。

downloadSpeed: 总体下载速度（字节/秒）。
uploadSpeed: 总体上传速度（字节/秒）。
numActive: 活动下载数量。
numWaiting: 等待下载数量。
numStopped: 当前会话中停止的下载数量。此值受 --max-download-result 选项的限制。
numStoppedTotal: 当前会话中已停止的下载数量，*未*受到 --max-download-result 选项限制。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getGlobalStat'})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'downloadSpeed': u'21846',
             u'numActive': u'2',
             u'numStopped': u'0',
             u'numWaiting': u'0',
             u'uploadSpeed': u'0'}}

XML-RPC 示例

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getGlobalStat()
>>> pprint(r)
{'downloadSpeed': '23136',
 'numActive': '2',
 'numStopped': '0',
 'numWaiting': '0',
 'uploadSpeed': '0'}

aria2.purgeDownloadResult([secret])¶: 此方法清除已完成/出错/已删除的下载以释放内存。此方法返回``OK``。

aria2.removeDownloadResult([secret, ]gid)¶

此方法从内存中删除由 gid 表示的已完成/出错/已删除的下载。成功时此方法返回``OK``。

以下示例将移除下载 GID#2089b05ecca3d829 的下载结果。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.removeDownloadResult',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'}

XML-RPC 示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.removeDownloadResult('2089b05ecca3d829')
'OK'

aria2.getVersion([secret])¶

此方法返回 aria2 的版本和已启用功能的列表。响应是一个结构，包含以下键。

version: aria2 的版本号，以字符串形式给出。
enabledFeatures: 已启用功能的列表。每个功能均为字符串形式。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getVersion'})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'enabledFeatures': [u'Async DNS',
                                  u'BitTorrent',
                                  u'Firefox3 Cookie',
                                  u'GZip',
                                  u'HTTPS',
                                  u'Message Digest',
                                  u'Metalink',
                                  u'XML-RPC'],
             u'version': u'1.11.0'}}

XML-RPC 示例

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getVersion()
>>> pprint(r)
{'enabledFeatures': ['Async DNS',
                     'BitTorrent',
                     'Firefox3 Cookie',
                     'GZip',
                     'HTTPS',
                     'Message Digest',
                     'Metalink',
                     'XML-RPC'],
 'version': '1.11.0'}

aria2.getSessionInfo([secret])¶

此方法返回会话信息。响应是一个结构，包含以下键。

sessionId: 会话 ID，在每次调用 aria2 时生成。

JSON-RPC 示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getSessionInfo'})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': {u'sessionId': u'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}}

XML-RPC 示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.getSessionInfo()
{'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}

aria2.shutdown([secret])¶: 此方法关闭 aria2。此方法返回``OK``。

aria2.forceShutdown([secret])¶: 此方法强制关闭 aria2()。此方法的行为类似于未执行任何需花费时间的操作，例如首先联系 BitTorrent 跟踪器以注销下载，且返回``OK``。

aria2.saveSession([secret])¶: 此方法将当前会话保存到由 --save-session 选项指定的文件中。如果成功，此方法返回``OK``。

system.multicall(methods)¶

此方法将多个方法调用封装成单个请求。methods 是一个包含结构的数组。结构包含两个键： methodName 和 params。 methodName 是要调用的方法名称，params 是包含对方法调用的参数的数组。此方法返回一个响应数组。元素将是包含该方法调用的返回值的单一数组，或者如果封装的方法调用失败，则是故障元素的结构。

在以下示例中，我们添加了 2 个下载。第一个是 http://example.org/file，第二个是 file.torrent。

JSON-RPC示例

>>> import urllib2, json, base64
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'system.multicall',
...                       'params':[[{'methodName':'aria2.addUri',
...                                   'params':[['http://example.org']]},
...                                  {'methodName':'aria2.addTorrent',
...                                   'params':[base64.b64encode(open('file.torrent').read())]}]]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [[u'2089b05ecca3d829'], [u'd2703803b52216d1']]}

JSON-RPC还支持批量请求，如JSON-RPC 2.0规范中所述:

>>> jsonreq = json.dumps([{'jsonrpc':'2.0', 'id':'qwer',
...                        'method':'aria2.addUri',
...                        'params':[['http://example.org']]},
...                       {'jsonrpc':'2.0', 'id':'asdf',
...                        'method':'aria2.addTorrent',
...                        'params':[base64.b64encode(open('file.torrent').read())]}])
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
[{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'2089b05ecca3d829'},
 {u'id': u'asdf', u'jsonrpc': u'2.0', u'result': u'd2703803b52216d1'}]

XML-RPC示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> mc = xmlrpclib.MultiCall(s)
>>> mc.aria2.addUri(['http://example.org/file'])
>>> mc.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
>>> r = mc()
>>> tuple(r)
('2089b05ecca3d829', 'd2703803b52216d1')

system.listMethods()¶

该方法以字符串数组的形式返回所有可用的RPC方法。与其他方法不同，此方法不需要秘密令牌。这是安全的，因为此方法只是返回可用的方法名称。

JSON-RPC示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'system.listMethods'})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': [u'aria2.addUri',
             u'aria2.addTorrent',
...

XML-RPC示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.system.listMethods()
['aria2.addUri', 'aria2.addTorrent', ...

system.listNotifications()¶

该方法以字符串数组的形式返回所有可用的RPC通知。与其他方法不同，此方法不需要秘密令牌。这是安全的，因为此方法只是返回可用的通知名称。

JSON-RPC示例

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'system.listNotifications'})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': [u'aria2.onDownloadStart',
             u'aria2.onDownloadPause',
...

XML-RPC示例

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.system.listNotifications()
['aria2.onDownloadStart', 'aria2.onDownloadPause', ...

错误处理¶

通过JSON-RPC，aria2返回一个包含``code``中的错误码和``message``中的错误消息的JSON对象。

通过XML-RPC，aria2返回``faultCode=1``和``faultString``中的错误消息。

选项¶

可用与 --input-file 相同的选项。查看输入文件子节以获取完整的选项列表。

在选项结构中，name元素是选项名称（不包含前导 --），value元素是参数的字符串。

JSON-RPC示例¶

{'split':'1', 'http-proxy':'http://proxy/'}

XML-RPC示例¶

<struct>
  <member>
    <name>split</name>
    <value><string>1</string></value>
  </member>
  <member>
    <name>http-proxy</name>
    <value><string>http://proxy/</string></value>
  </member>
</struct>

允许在命令行上多次使用 header 和 index-out 选项。由于在结构中名称应该是唯一的（许多XML-RPC库实现使用哈希或字典进行结构），单个字符串是不够的。为了克服这个限制，您可以将值作为数组以及字符串。

JSON-RPC示例¶

{'header':['Accept-Language: ja', 'Accept-Charset: utf-8']}

XML-RPC示例¶

<struct>
  <member>
    <name>header</name>
    <value>
      <array>
        <data>
          <value><string>Accept-Language: ja</string></value>
          <value><string>Accept-Charset: utf-8</string></value>
        </data>
      </array>
    </value>
  </member>
</struct>

以下示例添加了具有两个选项 dir 和 header 的下载。 header 选项需要两个值，因此它使用列表:

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> opts = dict(dir='/tmp',
...             header=['Accept-Language: ja',
...                     'Accept-Charset: utf-8'])
>>> s.aria2.addUri(['http://example.org/file'], opts)
'1'

JSON-RPC 使用 HTTP GET

JSON-RPC 接口还支持通过 HTTP GET 发送请求。GET 参数中的编码方案基于 JSON-RPC over HTTP Specification [2008-1-15(RC1)]。

GET 参数的编码方式如下:

/jsonrpc?method=METHOD_NAME&id=ID&params=BASE64_ENCODED_PARAMS

method 和 id 始终被视为 JSON 字符串，并且它们的编码必须是 UTF-8。

例如，使用 id='foo' 对 aria2.tellStatus('2089b05ecca3d829') 进行编码如下所示:

/jsonrpc?method=aria2.tellStatus&id=foo&params=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D

params 参数是 Base64 编码的 JSON 数组，通常出现在 JSON-RPC 请求对象的 params 属性中。在上面的示例中，params 是 ["2089b05ecca3d829"]，因此:

["2089b05ecca3d829"] --(Base64)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0=
             --(Percent Encode)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D

JSON-RPC 接口还支持 JSONP。您可以在 jsoncallback 参数中指定回调函数:

/jsonrpc?method=aria2.tellStatus&id=foo&params=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D&jsoncallback=cb

对于批量请求，method 和 id 参数不应被指定。整个请求必须在 params 参数中指定。例如，一个批量请求:

[{'jsonrpc':'2.0', 'id':'qwer', 'method':'aria2.getVersion'},
 {'jsonrpc':'2.0', 'id':'asdf', 'method':'aria2.tellActive'}]

必须被编码如下:

/jsonrpc?params=W3sianNvbnJwYyI6ICIyLjAiLCAiaWQiOiAicXdlciIsICJtZXRob2QiOiAiYXJpYTIuZ2V0VmVyc2lvbiJ9LCB7Impzb25ycGMiOiAiMi4wIiwgImlkIjogImFzZGYiLCAibWV0aG9kIjogImFyaWEyLnRlbGxBY3RpdmUifV0%3D

JSON-RPC over WebSocket¶

JSON-RPC over WebSocket使用与JSON-RPC over HTTP相同的方法签名和响应格式。支持的WebSocket版本为13，详细信息请参见 RFC 6455。

要向RPC服务器发送RPC请求，需要在Text帧中发送一个序列化的JSON字符串。RPC服务器的响应也是以Text帧传递的。

通知¶

RPC服务器可能向客户端发送通知。通知是单向的，因此接收通知的客户端不应该对其做出响应。通知的方法签名与普通方法请求类似，但缺少id键。params键的值是该通知携带的数据。值的格式取决于通知方法。以下通知方法已定义。

aria2.onDownloadStart(event)¶

当下载开始时将发送此通知。event 类型为struct，包含以下键。值类型为string。

gid: 下载的GID。

aria2.onDownloadPause(event)¶: 当下载暂停时将发送此通知。event 与 aria2.onDownloadStart() 方法的*event*参数相同。

aria2.onDownloadStop(event)¶: 当用户停止下载时将发送此通知。event 与 aria2.onDownloadStart() 方法的*event*参数相同。

aria2.onDownloadComplete(event)¶: 当下载完成时将发送此通知。对于BitTorrent下载，当下载完成并停止做种时将发送此通知。event 与 aria2.onDownloadStart() 方法的*event*参数相同。

aria2.onDownloadError(event)¶: 当下载由于错误而停止时将发送此通知。event 与 aria2.onDownloadStart() 方法的*event*参数相同。

aria2.onBtDownloadComplete(event)¶: 当Torrent下载完成但仍在进行做种时将发送此通知。 event 与 aria2.onDownloadStart() 方法的*event*参数相同。

示例 XML-RPC 客户端代码¶

以下 Ruby 脚本将 http://localhost/aria2.tar.bz2 添加到 aria2c（在 localhost 上运行），并使用选项 --dir=/downloads 打印 RPC 响应：

#!/usr/bin/env ruby

require 'xmlrpc/client'
require 'pp'

client=XMLRPC::Client.new2("http://localhost:6800/rpc")

options={ "dir" => "/downloads" }
result=client.call("aria2.addUri", [ "http://localhost/aria2.tar.bz2" ], options)

pp result

如果你是 Python 爱好者，你可以使用 xmlrpclib（Python3 使用 xmlrpc.client）来与 aria2 进行交互：：

import xmlrpclib from pprint import pprint

s = xmlrpclib.ServerProxy(”http://localhost:6800/rpc”) r = s.aria2.addUri([”http://localhost/aria2.tar.bz2”], {“dir”:”/downloads”}) pprint(r)

杂项¶

控制台输出¶

在下载文件时，aria2 在控制台上打印输出，显示下载进度。控制台输出如下所示：

[#2089b0 400.0KiB/33.2MiB(1%) CN:1 DL:115.7KiB ETA:4m51s]

本节描述了这些数字和字符串的含义。

#NNNNNN: GID 的前 6 个字符组成的十六进制字符串。GID 是 aria2 内部每个下载的唯一 ID。当使用 RPC 接口与 aria2 进行交互时，GID 非常有用。
X/Y(Z%): 已完成长度，总文件长度及其进度。如果使用 --select-file，则为选定文件的总和。
SEED: 当 aria2 在种子下载完成后进行做种时的分享比率。
CN: aria2 建立的连接数。
SD: aria2 连接的做种者数。
DL: 下载速度（每秒字节数）。
UL: 上传速度（每秒字节数）和已上传字节数。
ETA: 预计完成下载的时间。

当有多个下载正在进行时，为了显示多个下载的信息，上述描述的部分信息将被省略。整体下载和上传速度将显示在行的开头。

当 aria2 分配文件空间或验证校验和时，它还会打印这些操作的进度：

FileAlloc: GID、已分配长度和总长度（以字节为单位）。
Checksum: GID、已验证长度和总长度（以字节为单位）。

示例¶

HTTP/FTP 分段下载¶

下载一个文件¶

$ aria2c "http://host/file.zip"

Note

要停止下载，请按 Ctrl-C。您可以通过在同一目录中使用相同的参数运行 aria2c 来恢复传输。只要它们指向相同的文件，您可以更改 URI。

从两个不同的 HTTP 服务器下载文件¶

$ aria2c "http://host/file.zip" "http://mirror/file.zip"

使用多个连接从一个主机下载文件¶

$ aria2c -x2 -k1M "http://host/file.zip"

Note

-x 选项指定了允许的连接数，而 -k 选项指定了块的大小。

同时从 HTTP 和 FTP 服务器下载文件¶

$ aria2c "http://host1/file.zip" "ftp://host2/file.zip"

同时下载在一个文本文件中列出的文件¶

$ aria2c -ifiles.txt -j2

Note

-j 选项指定了并行下载的数量。

使用代理¶

对于 HTTP:

$ aria2c --http-proxy="http://proxy:8080" "http://host/file"

$ aria2c --http-proxy="http://proxy:8080" --no-proxy="localhost,127.0.0.1,192.168.0.0/16" "http://host/file"

对于 FTP:

$ aria2c --ftp-proxy="http://proxy:8080" "ftp://host/file"

Note

有关详细信息，请参阅 --http-proxy、--https-proxy、--ftp-proxy、--all-proxy 和 --no-proxy。您可以在环境变量中指定代理。请参阅环境章节。

使用带授权的代理¶

$ aria2c --http-proxy="http://username:password@proxy:8080" "http://host/file"

$ aria2c --http-proxy="http://proxy:8080" --http-proxy-user="username" --http-proxy-passwd="password" "http://host/file"

Metalink 下载¶

使用远程 Metalink 下载文件¶

$ aria2c --follow-metalink=mem "http://host/file.metalink"

使用本地 metalink 文件进行下载¶

$ aria2c -p --lowest-speed-limit=4000 file.metalink

Note

要停止下载，请按 Ctrl-C。您可以通过在同一目录中使用相同的参数运行 aria2c 来恢复传输。

下载多个本地 metalink 文件¶

$ aria2c -j2 file1.metalink file2.metalink

仅下载选定的文件¶

$ aria2c --select-file=1-4,8 file.metalink

Note

使用 -S 选项将索引打印到控制台。

使用具有用户偏好的本地 metalink 文件进行文件下载¶

$ aria2c --metalink-location=jp,us --metalink-version=1.1 --metalink-language=en-US file.metalink

BitTorrent下载¶

使用远程BitTorrent文件下载文件¶

$ aria2c --follow-torrent=mem "http://host/file.torrent"

使用本地Torrent文件下载¶

$ aria2c --max-upload-limit=40K file.torrent

Note

–max-upload-limit指定最大上传速率。

Note

要停止下载，请按 Ctrl-C。您可以稍后通过在同一目录中使用相同的参数运行aria2c来恢复传输。

使用BitTorrent Magnet URI下载¶

$ aria2c "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn=aria2"

Note

不要忘记在命令行指定URI时使用单引号(')或双引号(")引起来包含``&``字符的BitTorrent Magnet URI。

下载2个种子文件¶

$ aria2c -j2 file1.torrent file2.torrent

并行通过Torrent和HTTP/FTP服务器下载文件¶

$ aria2c -Ttest.torrent "http://host1/file" "ftp://host2/file"

只下载特定文件（通常称为“选定下载”）¶

$ aria2c --select-file=1-4,8 file.torrent

Note

索引使用选项-S在控制台上打印。

下载.torrent文件，但不下载种子¶

$ aria2c --follow-torrent=false "http://host/file.torrent"

指定输出文件名¶

要为BitTorrent下载指定输出文件名，您需要知道种子中文件的索引（参见:option:–show-files <-S>）。例如，输出如下：

idx|path/length
===+======================
  1|dist/base-2.6.18.iso
   |99.9MiB
---+----------------------
  2|dist/driver-2.6.18.iso
   |169.0MiB
---+----------------------

要将’dist/base-2.6.18.iso’保存为’/tmp/mydir/base.iso’，将’dist/driver-2.6.18.iso’保存为’/tmp/dir/driver.iso’，请使用以下命令：

$ aria2c --dir=/tmp --index-out=1=mydir/base.iso --index-out=2=dir/driver.iso file.torrent

更改接收对等连接的监听端口¶

$ aria2c --listen-port=7000-7001,8000 file.torrent

Note

由于aria2不配置防火墙或路由器进行端口转发，因此您需要手动完成。

指定在种子下载完成后停止做种的条件¶

$ aria2c --seed-time=120 --seed-ratio=1.0 file.torrent

Note

在上面的示例中，程序在下载完成后120分钟内停止做种，或当做种比率达到1.0时停止做种。

限制上传速度¶

$ aria2c --max-upload-limit=100K file.torrent

启用IPv4 DHT¶

$ aria2c --enable-dht --dht-listen-port=6881 file.torrent

Note

DHT使用UDP。由于aria2不配置防火墙或路由器进行端口转发，因此您需要手动完成。

启用IPv6 DHT¶

$ aria2c --enable-dht6 --dht-listen-port=6881 --dht-listen-addr6=YOUR_GLOBAL_UNICAST_IPV6_ADDR

Note

aria2使用与IPv4相同的端口进行IPv6通信。

添加和删除跟踪器URI¶

忽略文件.torrent中定义的所有跟踪器Announce URI，并改为使用``http://tracker1/announce``和``http://tracker2/announce``：

$ aria2c --bt-exclude-tracker="*" --bt-tracker="http://tracker1/announce,http://tracker2/announce" file.torrent

更高级的HTTP特性¶

恢复由网页浏览器或其他程序启动的下载¶

$ aria2c -c -s2 "http://host/partiallydownloadedfile.zip"

Note

这仅在初始下载未被分段时可用。

SSL/TLS 客户端证书授权¶

指定一个 PKCS12 文件如下：

$ aria2c --certificate=/path/to/mycert.p12

Note

：option:–certificate 中指定的文件必须包含一个 PKCS12 编码的证书和密钥。密码必须为空。

或者，如果支持 PEM 文件，可以使用以下命令：

$ aria2c --certificate=/path/to/mycert.pem --private-key=/path/to/mykey.pem https://host/file

Note

：option:–private-key 中指定的文件必须是解密的；加密的密钥可能会导致未定义的行为。

使用给定的 CA 证书验证 SSL/TLS 服务器¶

$ aria2c --ca-certificate=/path/to/ca-certificates.crt --check-certificate https://host/file

Note

该选项仅在 aria2 编译时使用 GnuTLS 或 OpenSSL 时可用。 WinTLS 和 AppleTLS 将始终使用系统证书存储。可以将证书安装在该存储中，而不是使用 --ca-certificate。

RPC¶

使用 SSL/TLS 对 RPC 流量进行加密¶

指定一个服务器的 PKC12 文件：

$ aria2c --enable-rpc --rpc-certificate=/path/to/server.p12 --rpc-secure

Note

：option:–rpc-certificate 中指定的文件必须包含一个 PKCS12 编码的证书和密钥。密码必须为空。

或者，当支持 PEM 文件（GnuTLS 和 OpenSSL）时，可以如下指定服务器证书文件和私钥文件：

$ aria2c --enable-rpc --rpc-certificate=/path/to/server.crt --rpc-private-key=/path/to/server.key --rpc-secure

及更高级的功能¶

限制下载速度¶

每个下载：

$ aria2c --max-download-limit=100K file.metalink

整体：

$ aria2c --max-overall-download-limit=100K file.metalink

修复损坏的下载¶

$ aria2c -V file.metalink

Note

当与BitTorrent或带有块校验和的Metalink一起使用时，可以高效地修复损坏的下载。

如果下载速度低于指定限制，则断开连接¶

$ aria2c --lowest-speed-limit=10K file.metalink

参数化URI支持¶

你可以指定一组部分：

$ aria2c -P "http://{host1,host2,host3}/file.iso"

你可以指定数字序列：

$ aria2c -Z -P "http://host/image[000-100].png"

Note

如果URI不指向同一个文件，如上例所示，需要使用-Z选项。

你可以指定步长计数器：

$ aria2c -Z -P "http://host/image[A-Z:2].png"

验证校验和¶

$ aria2c --checksum=sha-1=0192ba11326fe2298c8cb4de616f4d4140213837 http://example.org/file

任意数量的URI、metalink、torrent的并行下载¶

$ aria2c -j3 -Z "http://host/file1" file2.torrent file3.metalink

BitTorrent加密¶

使用ARC4加密整个有效载荷（混淆）：

$ aria2c --bt-min-crypto-level=arc4 --bt-require-crypto=true file.torrent

另请参见¶

项目网站：https://aria2.github.io/

Metalink主页：http://www.metalinker.org/

Metalink下载描述格式：RFC 5854

版权¶

本程序是自由软件；您可以按照自由软件基金会发布的GNU通用公共许可证的条款，重新分发和/或修改它。您可以选择许可证的第2版，或者（根据您的选择）任何更高版本。

本程序分发的目的是希望它有用，但没有任何保证；甚至没有对适销性或特定用途适用性的暗示保证。请参阅 GNU通用公共许可证了解更多详情。

您应该已经随本程序收到了一份GNU通用公共许可证；如果没有，请写信给自由软件基金会，地址：美国波士顿富兰克林街51号，五楼，邮编02110-1301。

此外，作为特殊例外，版权所有者允许在某些条件下，如每个单独的源文件中所述，将本程序的部分代码与 OpenSSL库链接，并分发包括这两者的链接组合。您必须在所有方面遵守GNU通用公共许可证对于除OpenSSL之外的所有代码。如果您修改带有此例外的文件，您可以将此例外扩展到您版本的文件中，但您不是必须这样做。如果您不希望这样做，请从您的版本中删除此例外声明。如果您从程序中的所有源文件中删除此例外声明，则也请在此处删除它。

aria2c(1)¶

概要¶

描述¶

选项¶

基本选项¶

HTTP/FTP/SFTP 选项¶

HTTP特定选项¶

特定的FTP/SFTP选项¶

BitTorrent/Metalink 选项¶

BitTorrent 特定选项¶

Metalink特定选项¶

RPC选项¶

高级选项¶

选项注意事项¶

可选参数¶

单位（K 和 M）¶

URI, 磁力链接, 种子文件, MetaLink 文件¶

恢复下载¶

事件钩子¶

退出状态¶

环境¶

文件¶

aria2.conf¶

dht.dat¶

Netrc¶

控制文件¶

输入文件¶

服务器性能配置文件¶

RPC 接口¶

术语¶

RPC 授权秘密令牌¶

方法¶

错误处理¶

选项¶

JSON-RPC示例¶

XML-RPC示例¶

JSON-RPC示例¶

XML-RPC示例¶

JSON-RPC over WebSocket¶

通知¶

示例 XML-RPC 客户端代码¶

杂项¶

控制台输出¶

示例¶

HTTP/FTP 分段下载¶

下载一个文件¶

从两个不同的 HTTP 服务器下载文件¶

使用多个连接从一个主机下载文件¶

同时从 HTTP 和 FTP 服务器下载文件¶

同时下载在一个文本文件中列出的文件¶

使用代理¶

使用带授权的代理¶

Metalink 下载¶

使用远程 Metalink 下载文件¶

使用本地 metalink 文件进行下载¶

下载多个本地 metalink 文件¶

仅下载选定的文件¶

使用具有用户偏好的本地 metalink 文件进行文件下载¶

BitTorrent下载¶

使用远程BitTorrent文件下载文件¶

使用本地Torrent文件下载¶

使用BitTorrent Magnet URI下载¶

下载2个种子文件¶

并行通过Torrent和HTTP/FTP服务器下载文件¶

只下载特定文件（通常称为“选定下载”）¶

下载.torrent文件，但不下载种子¶

指定输出文件名¶

更改接收对等连接的监听端口¶

指定在种子下载完成后停止做种的条件¶

限制上传速度¶

启用IPv4 DHT¶

启用IPv6 DHT¶

添加和删除跟踪器URI¶

更高级的HTTP特性¶

加载 Cookie¶

恢复由网页浏览器或其他程序启动的下载¶

SSL/TLS 客户端证书授权¶

使用给定的 CA 证书验证 SSL/TLS 服务器¶

RPC¶

使用 SSL/TLS 对 RPC 流量进行加密¶