How to Save aria2 Session State to a File?

This article provides a quick overview and step-by-step guide on how to force the aria2 command-line download utility to save its current download session state to a file. By default, aria2 does not automatically save your download progress in a readable format unless configured to do so. This guide covers how to save your session automatically using the --save-session flag, how to specify the saving interval, and how to resume your downloads later using the saved session file.

Understanding the aria2 Session File

When downloading large files or managing multiple downloads simultaneously, unexpected interruptions like power outages or network drops can disrupt your progress. While aria2 is highly efficient, it requires a dedicated session file to remember the exact state of active, paused, or queued downloads. Without this file, you would have to manually re-add every URL or torrent file to restart your downloads.

Step 1: Saving the Session on Exit

The most common way to ensure your session is saved is to tell aria2 where to write the session data when the program terminates or encounters an error. You do this by using the --save-session option followed by the path to your desired text file.

aria2c --save-session=/path/to/session.txt "URL"

If you want aria2 to automatically create this file even if no downloads are currently active or if the file doesn’t exist yet, you should also include the --force-save option.

aria2c --save-session=/path/to/session.txt --force-save=true "URL"

Step 2: Saving the Session Periodically (Auto-Save)

Forcing a save only when the program exits might not protect you if your entire system crashes suddenly. To fix this, you can force aria2 to save its current state to the session file at regular time intervals using the --save-session-interval option. The interval is specified in seconds.

To save your download state every 60 seconds, use the following command:

aria2c --save-session=/path/to/session.txt --save-session-interval=60 "URL"

Step 3: How to Resume Downloads Using the Session File

Once you have successfully forced aria2 to save its session state to a file, you can easily restore all of your downloads the next time you open the terminal. Instead of passing the original download URLs, you pass the session file using the -i (or --input-file) option.

aria2c -i /path/to/session.txt

To maintain continuous protection, it is best practice to combine the input and output options into a single command. This ensures that aria2 reads your old progress and immediately begins saving your new progress to the exact same file:

aria2c -i /path/to/session.txt --save-session=/path/to/session.txt --save-session-interval=60

Making the Configuration Permanent

If you do not want to type these long commands every time you use the utility, you can add these settings to your global aria2 configuration file (usually located at ~/.aria2/aria2.conf on Linux/macOS).

Open your configuration file and add the following lines:

input-file=/path/to/session.txt
save-session=/path/to/session.txt
save-session-interval=60
force-save=true

With these lines in your configuration file, simply running aria2c without any extra arguments will automatically load your last session and continuously save your progress every minute.