How to Enable Debug Logging to a File in aria2?

This article provides a straightforward guide on how to configure the aria2 download utility to output detailed debug-level logs directly to a file. By default, aria2 operates quietly to save system resources, but enabling verbose debug logging is essential for troubleshooting failed downloads, analyzing network behavior, or diagnosing configuration errors. You will learn the specific command-line flags required, how to make these changes permanent using a configuration file, and what to look for within the generated log.

Understanding aria2 Log Levels

Before enabling logs, it helps to understand that aria2 categorizes its output into different severity levels. Debug logging is the most verbose tier available.

debug: Logs everything, including internal program states, minute network events, and raw protocol messages.
info: Logs general progress, file allocations, and standard connection milestones.
notice: The default level, showing important status changes and completed downloads.
warn/error: Logs only problems, issues, and critical failures.

Because debug captures massive amounts of data, it should generally only be enabled while you are actively troubleshooting.

Enabling Debug Logs via Command Line

The quickest way to enable debug-level logging to a file is by passing the --log and --log-level flags directly into your terminal command when starting a download.

Use the following command structure:

aria2c --log=/path/to/your/logfile.txt --log-level=debug "YOUR_DOWNLOAD_URL"

--log=: Specifies the absolute or relative path to the file where aria2 should write the log data. If the file does not exist, aria2 will create it.
--log-level=debug: Instructs aria2 to capture every single internal event, overriding the default notice level.

Enabling Debug Logs via Configuration File

If you run aria2 as a background daemon or prefer not to type long commands every time, you can permanently or semi-permanently enable logging through your aria2.conf file.

Open your aria2.conf file and add the following lines:

# Log file location
log=/var/log/aria2.log

# Set log level to debug for maximum verbosity
log-level=debug

Save the file and restart your aria2 process. Keep in mind that debug logs grow in size very quickly. If you leave this setting enabled permanently in your configuration file, ensure you have a log rotation system in place or manually clear the file to prevent it from consuming your disk space.

Verifying and Reading the Log

Once your download starts, you can verify that the logging is working by opening the specified file. A standard aria2 debug log entry includes a timestamp, the log level tag [DEBUG], the source code file name, and the specific event message.

If you are using a Unix-like system (Linux or macOS), you can watch the log populate in real-time by running the following command in a separate terminal window:

tail -f /path/to/your/logfile.txt