Learn Aria2 - Directory & Output File Management

#Introduction

The last six episodes downloaded a lot of data, but never discussed the one thing that determines the quality of your workflow in the real world: where all those files land, under what names, and how to make sure none of them are corrupted. Production servers are full of downloaded ISO files, but without tidy directory management and integrity verification, the work can quietly descend into chaos — files lost in random directories, old versions overwritten, or a large file that turns out to be broken only discovered after it's used.

This episode closes out the protocol material and covers the most practical aspects: -d and -o for destination and file name, aria2's behavior when names collide, the .aria2 control file, and how to verify the integrity of large files effectively.

#Setting the Directory and File Name

The two options most often used to control the destination: -d (alias --dir) sets the destination directory, and -o (alias --out) sets the file name on disk.

aria2c -d /srv/downloads -o latest-release.tar.gz \
  https://mirror.example.com/releases/app-2026.08.tar.gz

The file on disk is now latest-release.tar.gz, not the name the server provided. This is useful when the server-side name isn't descriptive, changes with every release, or contains characters that complicate other tooling.

One limitation to remember: -o applies to HTTP/FTP downloads given directly on the command line, and not to BitTorrent or Metalink — there the file name is already determined by the metadata. For torrents, use --index-out=<INDEX>=<PATH>, which maps a file index to a destination path, while --force-sequential makes file names be taken from URLs in order.

#File Name Conflicts

What if a file with the same name already exists in the destination directory? By default aria2 does an automatic rename: it appends a number before the extension. An existing app.tar.gz produces app.1.tar.gz, then app.2.tar.gz, and so on.

aria2c -d /srv/downloads https://mirror.example.com/app.tar.gz
aria2c -d /srv/downloads https://mirror.example.com/app.tar.gz
ls /srv/downloads

The result is two files: app.tar.gz and app.1.tar.gz. This behavior is controlled by --auto-file-renaming (enabled by default). For the opposite — overwriting an old file from scratch — use --allow-overwrite. The right choice depends on context: rename is safe for parallel downloads, overwrite is right for periodic updates that genuinely want to replace the old version.

#The .aria2 Control File

While a download is in progress, aria2 creates a control file next to the destination file with the .aria2 suffix — for example app.tar.gz.aria2. This small file records which chunks have already been downloaded, forming the basis of the --continue resume from episode 5.

It's this control file that lets resume happen without restarting from zero: aria2 reads the last position and continues from there. The file is usually deleted after the download completes. You can control how often the status is saved to disk via --auto-save-interval — the default of 60 seconds is a reasonable balance between resume safety and disk I/O.

#Verifying Large File Integrity

After spending hours downloading a 10 GiB file, you don't want to discover the damage only when the file is used. aria2 provides several verification layers:

aria2c --checksum=sha-256=4e3b7c2a9f1d5e6b8c7a1f2e3d4c5b6a7f8e9d0c \
  https://mirror.example.com/app.iso

--checksum sets a hash that must match for HTTP/FTP downloads. If it matches, the file is considered valid; if not, the download is retried.

aria2c -d /srv/iso --check-integrity=true \
  /srv/meta/debian-live-12.meta4

--check-integrity (or -V) validates an existing file against the available checksums. For BitTorrent and Metalink, which have piece checksums, the check happens per chunk — and only corrupted chunks are re-downloaded. Compare that with the whole-file approach: a hash mismatch means redoing everything from scratch. For files dozens of GiB in size, that's the difference between minutes and hours.

Combine it with --hash-check-only=true to merely check without downloading anything — useful for routine audits of a file collection in storage.

#File Allocation and Disk Integrity

There's one more option with a big impact on long-term reliability: --file-allocation. By default aria2 uses prealloc — reserving the full disk space before the download starts, so a mid-way failure won't obscure the file. On modern filesystems like ext4, btrfs, or xfs, falloc does the same instantly:

aria2c -d /srv/downloads --file-allocation=falloc \
  https://mirror.example.com/big-file.iso

On older filesystems like ext3 or FAT32, falloc isn't recommended; prealloc remains the safe choice. Allocating fully up front also signals a disk shortage as early as possible — far better than discovering it at the last second.

#Organizing Output via Input File

For larger workflows, don't configure every download one at a time. Combine the power of episode 6: a single input file that manages each file's destination. Every URI line is followed by option lines mapping the file to the right directory and name.

organize-batch.txt

# Monthly log archives
https://cdn.example.com/logs/2026-07.gz
  dir=/srv/logs/2026-07
  out=combined.log.gz
https://cdn.example.com/logs/2026-08.gz
  dir=/srv/logs/2026-08
  out=combined.log.gz

aria2c -i organize-batch.txt -j 4

With this pattern, the directory structure on disk follows the same convention in every batch: a directory per period, consistent file names. No more guessing "where was this file downloaded". A tidy structure isn't just a habit — it lets automation built on top of the download results (backup, indexing, processing) be safely assumed.

#Choosing Locations Consistently

Finally, one principle that ties it all together: decide your directory convention once, then make aria2 follow it automatically via the configuration from episode 8. An example of a simple structure:

/srv/downloads/
├── iso/        # operating system images
├── packages/   # application packages
└── backup/     # backup archives

dir in aria2.conf points to /srv/downloads, and per-URL dir= options place files into the right subdirectories. The combination of a global config and per-URL options produces a predictable, easily auditable file store.

#Closing

In episode 11 you set directories and file names with -d and -o, understood the automatic --auto-file-renaming for name conflicts, got to know the .aria2 control file and its role in resume, verified integrity with --checksum and --check-integrity, and chose the right file allocation strategy.

The most important takeaway: a download's reliability is decided after the file lands, not while it's in flight. Tidy directories and automatic checksum verification turn your file store from a suspicious pile into a trustworthy asset.

In the next episode, episode 12, we open the exit route: proxy and networking — routing all downloads through HTTP and SOCKS proxies, plus network optimization in various conditions. See you then!