Learn Aria2 - Basic File Download (HTTP/HTTPS)

#Introduction

After dissecting aria2's architecture in episode 2 — from the three ways to run aria2c to segment-based download — it's time for the most practical episode: downloading a real file over HTTP/HTTPS. This episode is a milestone, because from here on every command you learn can be used immediately for real work: fetching files from servers, downloading assets, and laying the foundation for the advanced features in later episodes.

The difference you'll feel from the very first command: aria2 writes files directly to disk, and by default it displays very informative progress — including the number of active connections and an estimated time to completion. That's no accident: it's designed as a downloader, not a request tool like curl.

#Your First Download

Open a terminal, go to a clean working directory, and run:

Your first download

aria2c https://example.com/file.iso

The output you'll see looks roughly like this:

Example output of your first download

[#c6f2a1 0.0MiB/2.0MiB(0%) CN:1 DL:0B ETA:0s]
 
Download Results:
gid   |stat|avg speed  |path/URI
======+====+===========+=======================================================
c6f2a1|OK  |   2.0MiB/s|/home/user/downloads/file.iso

The parts you need to understand from aria2's progress:

Element	Meaning
`#c6f2a1`	GID — the download's unique identity; used to control the download via RPC
`0.0MiB/2.0MiB(0%)`	Progress: downloaded / total
`CN:1`	Number of connections currently active
`DL:0B`	Current download speed
`ETA:0s`	Estimated time to completion

At the end, aria2 displays a Download Results summary — an OK line means the download finished, complete with the average speed and the saved file path. Learning to read this line early will help a lot, because every download (including ones controlled via RPC) reports itself in the same format.

Note

example.com is deliberately reserved by IANA for documentation — it's stable, light, and always available, so it's safe for practice. Check the result with ls — you'll see a file.iso in your working directory.

#Output to a Directory & File Name: `-d` and `-o`

By default aria2 downloads to the current working directory with the file name taken from the URL. To control both, aria2 provides two options: -d (or --dir) for the destination directory and -o (or --out) for the file name:

Save to a specific directory and name

aria2c -d /tmp/downloads -o ubuntu.iso https://example.com/file.iso

The command above saves the file as /tmp/downloads/ubuntu.iso. Directories that don't exist yet are created automatically by aria2. It's like choosing the "destination warehouse" before shipping — download results won't mix with other working files.

Tip

The -o option doesn't apply to BitTorrent and Metalink downloads — for those two types, the file name comes from the .torrent or .meta4 metadata. We'll cover that in episodes 10 to 12. For regular HTTP/HTTPS downloads, -o always works.

#Output & Logging

Large file downloads can run for hours, and you can't stare at the screen the whole time. Aria2 gives you full control over output and logging:

Option	Purpose
`--summary-interval=SEC`	How often progress summaries are printed, in seconds
`--console-log-level=LEVEL`	Level of log detail in the terminal
`-q`	Quiet mode — turns off progress and logs
`--log=FILE`	Writes logs to a file

The most useful example for long downloads:

Summary every 5 seconds and log to a file

aria2c --summary-interval=5 --log=/tmp/aria2.log https://example.com/file.iso

The --console-log-level levels are ordered from the most to the least detail:

Level	Detail	When to Use
`debug`	Everything including internal debug info	Investigating difficult problems
`info`	Normal info including progress	Manual sessions
`notice`	Important events only	Default
`warn`	Only warnings and errors	Clean sessions for scripts
`error`	Only fatal errors	Quietest

A combination widely used in production: -q for scripts (silent), --log to keep a history, and a larger --summary-interval for very long downloads so the terminal isn't flooded with lines.

#Common Pitfalls

Running in the wrong directory. Downloads land in the current working directory. Always check pwd if the file location matters, or use -d explicitly.
A build without the HTTPS feature. If Enabled Features in aria2c --version doesn't include HTTPS, every https:// download will fail. Make sure your build is healthy, as we checked in episode 0.
-o on BitTorrent or Metalink. This option doesn't apply to those two download types — use it for HTTP/HTTPS only.
The terminal looks "frozen". If output isn't redirected to a file, progress refreshes every second. On small files the download finishes so quickly that only the summary remains — that's normal, not an error.

#Closing

In episode 3, you ran your first file download over HTTP/HTTPS: understanding aria2's progress elements (GID, CN, DL, ETA) and the Download Results format, setting the destination directory with -d, renaming files with -o, and controlling output and logging with --summary-interval, --console-log-level, -q, and --log.

Key takeaways:

aria2c URL downloads to the current working directory with the file name from the URL.
-d DIR sets the destination directory; -o NAME sets the file name.
aria2's progress shows GID, percentage, connections, speed, and ETA — learn to read it.
--summary-interval sets the summary frequency; -q silences output; --log keeps a history.

In the next episode, episode 4, we'll cover multi-connection & multi-source — releasing aria2's default brakes with -x 16 -s 16, setting the minimum segment size with -k, and downloading from many mirrors at once to maximize bandwidth. See you in episode 4!