A download that dies at 90 percent on a flaky connection is exactly what aria2c is built to survive. You will finish with a repeatable aria2c workflow for HTTP or HTTPS downloads: put files in a known directory, use several connections only when the server permits it, resume an interrupted transfer, and verify the result when you have a digest. The examples target the installed Debian package, aria2 1.37.0, whose command is aria2c.
Prerequisites: a shell, the aria2 package, a URL you are authorised to fetch, and enough disk space. Allow about 10 minutes for a first download and a few more minutes to adapt the commands. No command below needs elevated privileges when the destination belongs to your user. Do not use sudo to hide a permissions problem: it can leave root-owned files that your normal aria2c process cannot resume.
Check the binary and inspect the option groups you are likely to use:
aria2c --version
aria2c --help=#basic
aria2c --help=#checksumOn the machine described here, the first command reports aria2 version 1.37.0. The manpage is dated 16 April 2024 and documents this build. Options can change between releases, so keep that version in mind when copying a command to another host.
Create a private working directory and download one URL into it:
mkdir -p "$HOME/Downloads/aria2"
aria2c --no-conf --dir="$HOME/Downloads/aria2" \
'https://downloads.example.org/releases/example-1.2.3.tar.xz'--dir selects the directory for downloaded data. --no-conf makes this run independent of a user configuration file, which is useful while testing: aria2 normally reads $HOME/.aria2/aria2.conf, or the XDG configuration path when the legacy file is absent. Remove --no-conf once you have inspected and deliberately configured that file.
The output should show a download row with a percentage, speed and an eventual completed state. Verify the file without trusting the progress display alone:
ls -lh "$HOME/Downloads/aria2/example-1.2.3.tar.xz"Replace the host and filename with a real release URL. A made-up example domain will fail, as it should.
For a server that supports range requests, allow a small number of connections to one file:
aria2c --no-conf --dir="$HOME/Downloads/aria2" \
--split=4 --max-connection-per-server=4 --min-split-size=10M \
'https://downloads.example.org/releases/example-1.2.3.tar.xz'--split controls the number of connections used for a download, while --max-connection-per-server caps connections to one server. The installed defaults are 5 concurrent queue items, 1 connection per server, and a 20M minimum split size. More connections do not guarantee more speed and may trigger rate limits or violate a provider's terms. Start small and remove these options if the server rejects range requests.
For separate files, put unquoted URLs in an input file, one item per line, then limit item concurrency:
aria2c --no-conf --dir="$HOME/Downloads/aria2" \
--input-file=release-urls.txt --max-concurrent-downloads=2Lines beginning with # are comments. Do not quote URLs inside this file. A tab can separate multiple sources for the same item. Check the queue's final paths with find "$HOME/Downloads/aria2" -maxdepth 1 -type f -printf '%f\n'.
Stop with Ctrl-C, then rerun the same download in the same directory with --continue:
aria2c --no-conf --continue --dir="$HOME/Downloads/aria2" \
'https://downloads.example.org/releases/example-1.2.3.tar.xz'For HTTP(S) and FTP, --continue resumes a sequential partial file when the server supports it. aria2 stores progress in a neighbouring control file ending in .aria2; it normally removes that file after completion. Do not delete the control file while a transfer is incomplete. If the server cannot resume, aria2 may restart or refuse to create a resumable control file.
To undo a failed or unwanted partial download, stop aria2c and remove only the named data file and its matching .aria2 control file after checking the path. This is destructive: do not use a broad wildcard in a directory containing other downloads.
Pass the publisher's exact digest and ask aria2c to check the HTTP(S) or FTP result:
aria2c --no-conf --check-integrity=true \
--checksum=sha-256=REPLACE_WITH_64_HEX_CHARACTERS \
--dir="$HOME/Downloads/aria2" \
'https://downloads.example.org/releases/example-1.2.3.tar.xz'The local manpage says --checksum accepts a hash type and hexadecimal digest, and that this form applies to HTTP(S) and FTP. Use the algorithm and digest published by the same trusted project, not one copied from an unverified comment. If the check fails, aria2 can redownload from scratch. Treat that as a useful stop signal, not as a reason to disable verification.
Once the commands work, a configuration file can hold stable preferences such as dir=/home/REPLACE_ME/Downloads/aria2, max-concurrent-downloads=2 and continue=true. It uses one name=value option per line, with # comments. Keep credentials out of command history and logs. If a proxy password or other secret must be present in aria2.conf, restrict it with chmod 600 /path/to/aria2.conf and check ownership. Do not paste secrets into a guide, ticket or shell transcript.
The same caution applies to --log. Without that option aria2 writes no disk log; --log=- writes to standard output, which can be captured by a service manager or terminal recording. If you need a log, choose its path deliberately and review it for URLs or credentials before sharing it.
--out is relative to --dir and is for direct command-line URIs. The manpage says it is ignored for input-file sequential mode and cannot name Metalink or BitTorrent downloads.& separators would otherwise be interpreted by the shell.--no-conf while diagnosing a command that behaves differently on two machines, then compare their configuration files.aria2c --version identifies the build you tested.