What happens if aria2 finds a file with the same name?

When using the aria2 download utility, encountering an existing file with the same name in the target directory triggers specific default behaviors designed to prevent accidental data loss. By default, aria2 will not overwrite your existing file; instead, it automatically renames the newly downloaded file by appending a suffix or, in some cases, attempts to resume the download if the file is incomplete. This article explores how aria2 handles these name collisions, the mechanics behind its auto-renaming feature, and the configuration options available to customize this behavior to suit your workflow.

The Default Behavior: Auto-Renaming

If you start a download and a file with the exact same filename already exists in the destination directory, aria2 protects the original file. It achieves this by renaming the new download using a specific naming convention:

• Suffix Appending: aria2 appends a dot and an incrementing number to the filename before the extension (or at the end of the file if there is no extension). For example, if you are downloading video.mp4 and it already exists, the new file will be saved as video.1.mp4.
• Subsequent Collisions: If video.1.mp4 also exists, the next download will be named video.2.mp4, continuing sequentially.

Conditional File Resuming

There is an important exception to the auto-renaming rule. If aria2 detects a matching control file (a .aria2 file) alongside the existing file, it assumes the previous download was interrupted. Instead of creating a renamed duplicate, aria2 will read the control file and attempt to resume the download from where it left off, saving time and bandwidth.

Customizing the Collision Behavior

If the default auto-renaming behavior does not fit your specific use case, aria2 provides command-line flags and configuration options to alter how it responds to existing files.

• --auto-file-renaming This option is enabled (true) by default. If you want to disable the automatic renaming feature entirely, you can set it to false. > Warning: If you set --auto-file-renaming=false and a file with the same name exists, aria2 will fail the download and log an error rather than overwriting the file.

• --allow-overwrite By default, aria2 is cautious and will not overwrite completed files. If your goal is to always replace the old file with the fresh download, you must explicitly enable the overwrite flag by adding --allow-overwrite=true to your command. When this is active, aria2 will bypass the renaming process and overwrite the pre-existing file.

• --conditional-get For HTTP/HTTPS downloads, you can use the --conditional-get=true option. When an existing file is found, aria2 will ask the server if the remote file is newer than the local one. If the server indicates the file has not changed, aria2 will skip the download entirely. If it has changed, aria2 will download the new version (respecting your overwrite or renaming settings).