Can aria2 Automatically Run a Script After Download?

The command-line download utility aria2 can automatically execute a script upon the completion of a download. This automation is achieved by utilizing the --on-download-complete option, which passes specific event parameters to a designated shell script or executable. This article provides a quick guide on how to configure this feature, set up a compatible script, and troubleshoot common execution issues.

How to Configure aria2 for Script Execution

To trigger a script when a download finishes, you must use the --on-download-complete option followed by the path to your executable script. This can be passed directly in the command line or defined within your aria2.conf configuration file.

Command Line Example

aria2c --on-download-complete=/path/to/script.sh "https://example.com/file.zip"

Configuration File Example (aria2.conf)

on-download-complete=/path/to/script.sh

How aria2 Passes Arguments to the Script

When aria2 calls the script, it automatically appends three specific arguments in a strict sequence. Your script can capture these variables to perform conditional actions based on which file was downloaded.

  • $1 (GID): The unique Download GID assigned by aria2.
  • $2 (File Count): The total number of files in the download.
  • $3 (File Path): The absolute path of the first downloaded file.

Creating a Sample Post-Download Script

Below is a basic Bash script template that utilizes the arguments provided by aria2. It logs the completion details and can be customized to move files, send notifications, or trigger media library refreshes.

#!/bin/bash

# Assigning aria2 arguments to readable variables
GID=$1
FILE_NUM=$2
FILE_PATH=$3

# Example action: Log the completed download
echo "Download complete! GID: $GID, Files: $FILE_NUM, Path: $FILE_PATH" >> /var/log/aria2_downloads.log

# Add your custom automation commands below (e.g., extracting a zip, moving files)

Important: Before aria2 can run your script, you must grant it execution permissions using the command chmod +x /path/to/script.sh.

Troubleshooting Common Issues

If your script fails to trigger after a successful download, check the following common pitfalls:

  • File Permissions: Ensure the user running the aria2c process has explicit permissions to execute the script and write to any target directories.
  • Absolute Paths: Always use absolute paths for both the script location and any directories referenced inside the script, as aria2 may execute from a different working directory.
  • Environment Variables: Scripts executed by aria2 may run with a minimal environment. Define full paths for external commands (like /usr/bin/curl instead of just curl) within the script.