Learn Aria2 - Batch Download & Input File

#Introduction

In episode 5 you split one file across several parallel connections and resumed interrupted downloads with --continue. Up to that point, one command still meant one file. Yet real-world needs are rarely that simple: you have 50 ISO files from a staging mirror, 30 dataset packages, or 100 log archives to pull at once. Running commands one by one wastes time and invites mistakes. This episode introduces aria2's batch mode — downloading many URLs from a single text file, setting per-URL options, and managing queues of dozens or even hundreds of downloads in a single process.

Why does this matter? Because in automation, doing many things at once is the norm, not the exception. aria2 is designed as a download manager, not merely a client: it accepts a job list, runs part of it in parallel, then finishes the rest sequentially. That very ability is what distinguishes aria2 from wget or curl.

#Downloading Many URLs with an Input File

The core of batch mode is the -i option, also known as --input-file. Instead of writing URLs as command arguments, you put all URLs in a single text file — one URL per line — then hand aria2 that file's path.

run-batch.sh

aria2c -i urls.txt -d /tmp/downloads

One command, three files. aria2 reads each line as one download item and handles them all in the same process. One detail that often trips people up: URLs inside the input file must not be wrapped in quotes. Unlike in the shell, this file's contents are read raw by aria2 — quotes would be treated as part of the URL and the download would fail.

Tip

The input file can also be read from stdin with aria2c -i -. This lets you build a URL list through a pipeline, for example grep '\.iso$' daftar.txt | aria2c -i - — a combination that's very handy in scripts.

#Per-Line Format and Per-URL Options

The input file isn't just a URL list. Its format has three features: one line for one file entity, several mirror URLs on the same line, and special option lines that follow a URL.

Line-by-line explanation:

Several URLs on one line — separated by TAB characters (press the Tab key) — mean those URLs are mirrors of the same file. aria2 uses them in parallel, exactly the multi-source feature from episode 5.
Option lines — starting with a space or TAB and holding one option per line — apply to the URL above them. Here split=8 forces eight connections for the ISO file, while dir= and out= set the backup file's destination.
The local file name is controlled by out=. Useful when the server-side name isn't descriptive, for example saving a long parameterized URL as out=rilis.zip.

Note that the dir option on an option line is per-URL, while -d on the command line is global. The more specific one always wins.

#Comments to Document Your Queue

Lines starting with # are treated as comments and skipped. The benefit isn't just cosmetic — a long download list without labels is hard to maintain, especially when several people on a team work on it in turn.

#The Download Queue: Order and Parallelism

When the file holds many URLs, aria2 creates a queue. By default it runs up to five items at once — the value of --max-concurrent-downloads — and the rest wait in line. Finished items leave the queue, then the next items take their place.

Imagine a supermarket with several cash registers. --max-concurrent-downloads is the number of open registers; the URL list is the queue of customers. Setting this value means controlling how many downloads run simultaneously without making them all fight over bandwidth. Set it to 2 for gentle downloads on a small connection, or 10 to pull many files at once on a high-volume server.

boost-six-at-once.sh

aria2c -i urls.txt -j 6 -x 4 -d /tmp/downloads

Don't confuse this with the -x option (--max-connection-per-server) from episode 5: -x governs connections within one file, while -j governs how many files are processed at once. They work at different layers and complement each other.

#Managing Large Queues

The bigger the queue, the more important a few settings become:

--deferred-input=true — aria2 no longer reads the entire input file upfront, but item by item as needed. This saves memory when the queue holds hundreds of thousands of URLs: aria2c -i urls.txt --deferred-input=true.
--max-download-result=<NUM> — limits how much download history is kept in memory after completion. Useful so very long batch processes don't pile up memory.
--save-session=<FILE> — saves the status of all downloads (including running ones) to a file. In the next session, run aria2c -i session.txt and the queue resumes from the last position — like --continue, but for the entire queue.

Combining --save-session and --deferred-input is highly recommended for large download jobs that run overnight or get restarted periodically.

One more reminder: the list of valid input-file options is quite long — even continue=true can be a per-URL option line to make sure each item resumes if interrupted. The full list can be found in aria2's official documentation under Input File.

#Generating URL Lists from Other Commands

The input file doesn't have to be typed by hand. Because it's plain text, a URL list can come from other commands — and that's where batch download becomes truly powerful. A simple example: you have a list of archive names and want to build their URLs programmatically.

build-list.sh

ls /data/backup/*.tar.gz | \
  sed 's#^#https://cdn.example.com/backup/#' > daftar-untuk-unduh.txt
aria2c -i daftar-untuk-unduh.txt -j 3

A script like this can be planted in cron for periodic synchronization: the list is built, downloaded, and only the right files get pulled in. Combine it with --continue and --save-session, and you have a sync pipeline that can be re-run without fear of losing progress.

Tip

Because the input file is read raw without shell expansion, don't use special characters like $ or quotes inside it. If a URL contains characters you'd normally escape in the shell, write them as-is — that's what aria2 expects.

#Closing

In episode 6 you leveled up from a single-file client to a batch download manager: reading a URL list from an input file with -i, using the per-line format with mirrors and per-URL options, documenting queues with comments, limiting parallelism with --max-concurrent-downloads, and managing large queues with --deferred-input and --save-session.

The most important thing to take away: the input file changes how you think about downloads — from commands to data. URL lists can now be created, maintained, and processed like ordinary data: generated, filtered, and queued automatically.

In the next episode, episode 7, we switch protocols — from HTTP to FTP and SFTP: authentication, directory downloads, and the differences in how the two behave. See you then!