aria2 Integration

Integrate TrackersList with aria2 using community-maintained scripts that automatically update your aria2 configuration with the latest trackers.

Overview

aria2 integration scripts update the bt-tracker configuration option in your aria2.conf file, ensuring all BitTorrent downloads use the latest high-performance trackers from TrackersList.

Prerequisites

Before you begin, ensure you have:

aria2 installed and configured
Go or Bash environment
Write access to your aria2 configuration file
curl or wget for downloading tracker lists

Available Scripts

Multiple community tools are available for aria2 integration:

Go Script

Feature-rich Go implementation by rocket049

Bash Script 1

Lightweight bash script by HaleTom (Gist)

Bash Script 2

Alternative bash implementation by wuyuansushen

Go Script Installation

The Go script provides automatic updates and advanced features.

Install Go

Ensure Go is installed on your system:

go version

If not installed, download from golang.org.

Clone the repository

git clone https://github.com/rocket049/aria2-trackers.git
cd aria2-trackers

Build the tool

go build

This creates an aria2-trackers executable.

Configure aria2 path

The script needs to know where your aria2.conf is located. Common paths:

~/.config/aria2/aria2.conf (Linux)
~/.aria2/aria2.conf (Alternative Linux)
/etc/aria2/aria2.conf (System-wide)

Run the script

Execute the script to update trackers:

./aria2-trackers -c ~/.config/aria2/aria2.conf

The script will:

Download the latest TrackersList
Update the bt-tracker line in your config
Preserve other configuration options

Bash Script Installation

For a lightweight solution without Go dependencies, use one of the bash scripts.

Using HaleTom’s Gist Script

Download the script

wget https://gist.githubusercontent.com/HaleTom/fe873dc2f3c5bd14f7418efefc2b91a8/raw/aria2-update-trackers.sh
chmod +x aria2-update-trackers.sh

Edit configuration

Open the script and configure:

nano aria2-update-trackers.sh

Set:

Path to your aria2.conf file
TrackersList URL (default is usually fine)
Optional: RPC settings if you want to reload aria2 automatically

Run the script

./aria2-update-trackers.sh

Using wuyuansushen’s Script

Clone the repository

git clone https://github.com/wuyuansushen/aria2c_TrackersList.git
cd aria2c_TrackersList
chmod +x aria2c_TrackersList.sh

Configure the script

Edit the script to set your aria2 configuration path:

nano aria2c_TrackersList.sh

Execute

./aria2c_TrackersList.sh

Configuration File Format

The scripts modify the bt-tracker option in your aria2.conf file. After running a script, your config will contain:

bt-tracker=udp://tracker1.example.com:80/announce,udp://tracker2.example.com:80/announce,http://tracker3.example.com/announce

Trackers are comma-separated on a single line. The scripts handle formatting automatically.

Automation

Set up automatic tracker updates using cron or systemd timers.

Cron Setup

Create wrapper script

Create a script to update trackers and reload aria2:

cat > /usr/local/bin/update-aria2-trackers.sh << 'EOF'
#!/bin/bash

# Update trackers
/path/to/aria2-trackers -c ~/.config/aria2/aria2.conf

# Reload aria2 configuration (if using RPC)
aria2p call --secret="your-rpc-secret" aria2.changeGlobalOption bt-tracker="$(grep bt-tracker ~/.config/aria2/aria2.conf | cut -d'=' -f2)"
EOF

chmod +x /usr/local/bin/update-aria2-trackers.sh

Add cron job

crontab -e

Add entry to run weekly on Sundays at 3 AM:

0 3 * * 0 /usr/local/bin/update-aria2-trackers.sh >> /var/log/aria2-trackers.log 2>&1

Systemd Timer

Create service file

Create /etc/systemd/system/aria2-trackers.service:

[Unit]
Description=Update aria2 Trackers
After=aria2.service

[Service]
Type=oneshot
ExecStart=/usr/local/bin/update-aria2-trackers.sh
User=your-username

Create timer file

Create /etc/systemd/system/aria2-trackers.timer:

[Unit]
Description=Update aria2 Trackers Weekly

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target

Enable timer

systemctl daemon-reload
systemctl enable aria2-trackers.timer
systemctl start aria2-trackers.timer
systemctl status aria2-trackers.timer

Weekly updates are sufficient for most users. Daily updates may be excessive and put unnecessary load on TrackersList servers.

Tracker List Selection

Configure which TrackersList to use in your script:

# Top 20 performing trackers
TRACKER_URL="https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_best.txt"

Manual Configuration

To manually update trackers without scripts:

Download tracker list

curl https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_best.txt -o trackers.txt

Format for aria2

Convert the list to comma-separated format:

trackers=$(cat trackers.txt | grep -v '^$' | tr '\n' ',')
echo "bt-tracker=$trackers" > tracker-line.txt

Update aria2.conf

Edit your aria2.conf file:

nano ~/.config/aria2/aria2.conf

Replace or add the bt-tracker line with the content from tracker-line.txt.

Restart aria2

# If using systemd
systemctl restart aria2

# Or kill and restart manually
killall aria2c
aria2c --conf-path=~/.config/aria2/aria2.conf -D

Manual updates require repeating this process periodically to maintain optimal tracker performance. Automated scripts are strongly recommended.

Reloading aria2 Configuration

After updating trackers, you can reload aria2 without restarting:

Using RPC

If you have aria2 RPC enabled:

# Install aria2p (Python tool)
pip install aria2p

# Reload configuration
aria2p call --secret="your-rpc-secret" aria2.reload

Using aria2c RPC directly

# Using curl
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"aria2.changeGlobalOption","params":["token:YOUR_SECRET",{"bt-tracker":"tracker1,tracker2,tracker3"}]}' \
  http://localhost:6800/jsonrpc

Troubleshooting

Script can't find aria2.conf

Verify the config file path in the script
Common locations:
- ~/.config/aria2/aria2.conf
- ~/.aria2/aria2.conf
- /etc/aria2/aria2.conf
Check file permissions: ls -la ~/.config/aria2/aria2.conf

Trackers not being used

Verify the bt-tracker line was updated: grep bt-tracker ~/.config/aria2/aria2.conf
Restart aria2 to apply changes
Check aria2 logs for tracker connection attempts
Ensure BitTorrent is enabled in aria2: enable-dht=true and enable-peer-exchange=true

Script fails to download tracker list

Test URL accessibility: curl https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_best.txt
Check internet connectivity
Try using a mirror URL from TrackersList
Verify proxy settings if behind a proxy

Go script build fails

Ensure Go is properly installed:

go version
go env

If issues persist, try:

go clean
go mod tidy
go build

Permission denied errors

The script may not have write access to aria2.conf:

# Check permissions
ls -la ~/.config/aria2/aria2.conf

# Fix permissions if needed
chmod 644 ~/.config/aria2/aria2.conf

Advanced Configuration

Using Multiple Tracker Lists

Combine multiple TrackersList sources for maximum coverage:

#!/bin/bash

# Download multiple lists
curl https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_best.txt > trackers1.txt
curl https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_all_udp.txt > trackers2.txt

# Combine and deduplicate
cat trackers1.txt trackers2.txt | sort -u | grep -v '^$' > combined.txt

# Format for aria2
trackers=$(cat combined.txt | tr '\n' ',')
echo "bt-tracker=$trackers"

Custom Filtering

Filter trackers by protocol or domain:

# Only HTTPS trackers
curl https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_all.txt | grep '^https://' > https-only.txt

# Exclude specific domains
curl https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_best.txt | grep -v 'example.com' > filtered.txt

Additional Resources

aria2 Documentation

Official aria2 repository and documentation

aria2 Manual

Complete aria2 configuration reference

TrackersList Repository

View all available tracker lists

aria2p Tool

Python library and CLI for aria2 RPC

Getting Started

Tracker Lists

Integration Guides

Advanced

Overview

Prerequisites

Available Scripts

Go Script

Bash Script 1

Bash Script 2

Go Script Installation

Bash Script Installation

Using HaleTom’s Gist Script

Using wuyuansushen’s Script

Configuration File Format

Automation

Cron Setup

Systemd Timer

Tracker List Selection

Manual Configuration

Reloading aria2 Configuration

Using RPC

Using aria2c RPC directly

Troubleshooting

Advanced Configuration

Using Multiple Tracker Lists

Custom Filtering

Additional Resources

aria2 Documentation

aria2 Manual

TrackersList Repository

aria2p Tool

Build docs developers (and LLMs) love

Getting Started

Tracker Lists

Integration Guides

Advanced

​Overview

​Prerequisites

​Available Scripts

Go Script

Bash Script 1

Bash Script 2

​Go Script Installation

​Bash Script Installation

​Using HaleTom’s Gist Script

​Using wuyuansushen’s Script

​Configuration File Format

​Automation

​Cron Setup

​Systemd Timer

​Tracker List Selection

​Manual Configuration

​Reloading aria2 Configuration

​Using RPC

​Using aria2c RPC directly

​Troubleshooting

​Advanced Configuration

​Using Multiple Tracker Lists

​Custom Filtering

​Additional Resources

aria2 Documentation

aria2 Manual

TrackersList Repository

aria2p Tool

Build docs developers (and LLMs) love

Overview

Prerequisites

Available Scripts

Go Script Installation

Bash Script Installation

Using HaleTom’s Gist Script

Using wuyuansushen’s Script

Configuration File Format

Automation

Cron Setup

Systemd Timer

Tracker List Selection

Manual Configuration

Reloading aria2 Configuration

Using RPC

Using aria2c RPC directly

Troubleshooting

Advanced Configuration

Using Multiple Tracker Lists

Custom Filtering

Additional Resources