# aria2tui
Aria2tui is a TUI download management tool. It acts as a client for the aria2c download utility, facilitating bulk downloading, torrenting, queue control, the fine-tuning of download options (e.g., piece length, user-agent, max speed, etc.), downloading via proxy, and much more.
Aria2tui communicates with the aria2c daemon over RPC. The UI is provided by my TUI picker [listpick](https://github.com/grimandgreedy/listpick).
<!-- https://github.com/user-attachments/assets/07ab1f63-3a5e-42dd-bddb-56c948ecd620 -->
https://github.com/user-attachments/assets/7c77a13f-90c7-4e67-9946-7b7009c835ad
## Quickstart
Install aria2tui using pip:
```bash
python -m pip install aria2tui
```
Create a `config.toml` file and place it in `~/.config/aria2tui/`. Here is the default config:
<!-- ```bash -->
<!-- mkdir ~/.config/aria2tui/ && -->
<!-- wget https://raw.githubusercontent.com/grimandgreedy/aria2tui/refs/heads/master/src/aria2tui/data/config.toml -O ~/.config/aria2tui/config.toml -->
<!-- ``` -->
```toml
####################################################
## Default config for Aria2TUI
## Some common config options have been provided
## and commented for your convenience
####################################################
[general]
port = 6800
token = "1234"
url = "http://localhost"
# Used for starting and restarting.
startupcmds = ["aria2c"]
restartcmds = ["pkill aria2c && sleep 1 && aria2c"]
# startupcmds = ["systemctl --user start aria2d.service"]
# restartcmds = ["systemctl --user restart aria2d.service", "notify-send 'Aria2c has been restarted.'"]
# Used when "Edit Config" option is chosen in the main menu
ariaconfigpath = "~/.config/aria2/aria2.conf"
# File managers
## terminal_file_manager will open in the same terminal as Aria2TUI in a blocking fashion;
## gui_file_manager will fork a new process and open a new application.
terminal_file_manager = "yazi"
gui_file_manager = "kitty yazi"
# Launchers
## Note that the "open file(s) (grouped)" option still requires gio and xdg-mime.
launch_command = "xdg-open"
# launch_command = "termux-open"
# Data refresh time (in seconds) for the global stats and for the download data.
global_stats_timer = 1
refresh_timer = 2
# Scrolls by default
paginate = false
[appearance]
theme = 3
# Whether the right pane (DL Info, DL graphs) should be displayed by default when opening aria2tui
show_right_pane_default = false
# Which pane should be displayed first when the sidebar is opened.
# [0=DL Files (info), 1=speed graph, 2=progress graph, 3=download pieces]
right_pane_default_index = 0
```
**Note**: If you have not used aria2c before then download [this file](https://gist.github.com/qzm/a54559726896d5e6bf21adf2363ad334) and put it in ~/.config/aria2/.
After editing ~/.config/aria2tui/config.toml and ensuring that your url, port, and secret token are correct, you are all set to go:
```bash
aria2tui
```
Be aware that Aria2TUI makes use of:
- `nvim` for viewing/editing download options as well as adding URIs, magnet links and torrent files
- `xdg-open` and `gio` for determining default applications and opening files.
## Multiple config files
If you have multiple aria2c daemons you can specify another config file using the ARIA2TUI_CONFIG_PATH environment variable:
```
ARIA2TUI_CONFIG_PATH=/path/to/config/aria2c_torrents.toml aria2tui
ARIA2TUI_CONFIG_PATH=/path/to/config/aria_on_home_server_config.toml aria2tui
```
If you wish to use it regularly, then it may be useful to add aliases to your ~/.bashrc.
```
alias a2="python /path/to/aria2tui/aria2tui.py"
alias a2t="ARIA2TUI_CONFIG_PATH=/path/to/config/aria2c_torrents.toml aria2tui"
alias a2n="ARIA2TUI_CONFIG_PATH=/path/to/config/aria_on_home_server_config.toml aria2tui"
```
## Tips
- Press '?' to see the help page which will list the available keys.
- If you have problems starting aria2c, check that you have an aria2c config file at ~/.config/aria2/aria2.conf
- By default aria2tui will track the download that the cursor is on. This is usually what you want. However, sometimes you want to stay at a particular place in the download queue--perhaps you want to remain at the top and watch the currently active downloads.
- Press ~ and locate the **pin cursor (pc)** option.
- Note: The pin symbol will be shown in the footer to indicate the cursor tracking mode.
- If you are performing bulk operations and the downloads are changing state rapidly--e.g., hundreds of images are changing from active/waiting to completed--it is recommended to **toggle the auto-refresh** option to ensure data integrity while selecting which downloads to operate upon.
- This can be done by either:
- exiting to the main menu ('q') and going to "View Downloads"; or
- Pressing ~ and toggling auto-refresh.
- Note: The refresh symbol at the top right indicates that you are in auto-refresh mode.
## Other installation options
### Git repo
Clone rep
```bash
git clone https://github.com/grimandgreedy/Aria2TUI
```
Copy config and edit it accordingly:
```bash
mkdir ~/.config/aria2tui &&
cp Aria2TUI/src/aria2tui/data/config.toml ~/.config/aria2tui
```
Install the requirements:
```bash
python -m pip install -r requirements.txt
```
Now you can start Aria2TUI:
```bash
cd ./Aria2TUI/src
python -m aria2tui.aria2tui_app
```
```bash
alias a2="cd /path/to/Aria2TUI/src && python -m aria2tui.aria2tui_app"
```
## Features
- Dynamic display of downloads
- View active, queue, errored, stopped
- Sort/filter/search using regular expressions
- Add downloads with options
- Simply dump a list of links;
- or specify options:
- proxy
- User agent
- ... Many more!
- See [this section of the aria2c manual](https://aria2.github.io/manual/en/html/aria2c.html#input-file) for all available options all of which are supported
- Add magnet links and torrent files
- Operations on downloads:
- Pause/unpause
- Remove
- Change position in queue
- Open downloaded files
- Open download location (with yazi)
- Change download options by value of keys in nvim
- Select download(s) you wish to change the value
- Change save directory
- Specify proxy, proxy user, and proxy password
- Specify user-agent
- Specify download piece length
- ... Many more!
- See [this section of the aria2c manual](https://aria2.github.io/manual/en/html/aria2c.html#input-file) for all available options all of which are supported.
<!-- <div align="center"> <img src="assets/change_options.gif" alt="change_options" width="70%"> </div> -->
<div align="center"> <img src="https://raw.githubusercontent.com/grimandgreedy/aria2tui/refs/heads/master/assets/change_options.gif" alt="change_options" width="70%"> </div>
- View current options of download
- Retry download
- Interact with aria2 daemon
- Edit config
- Pause all
- Restart aria
- Global and particular download transfer speed *graphs*.
<!-- <div align="center"> <img src="assets/transfer_speed_graph.png" alt="speed_graph" width="70%"> </div> -->
<div align="center"> <img src="https://raw.githubusercontent.com/grimandgreedy/aria2tui/refs/heads/master/assets/transfer_speed_graph.png" alt="speed_graph" width="70%"> </div>
- Visual options
- Modify theme
- '~' to view settings and then select theme
<!-- <div align="center"> <img src="assets/themes.png" alt="themes" width="70%"> </div> -->
<div align="center"> <img src="https://github.com/grimandgreedy/aria2tui/blob/master/assets/themes.png?raw=true" alt="themes" width="70%"> </div>
- Show/hide columns
- Press Shift+Column_number to toggle or press '~' to view settings and find the column you wish to toggle.
- Quick-toggle footer: press '_'
## Important
While I use Aria2TUI every day, it is still in development and there are many things that still need to be cleaned up.
Some things that should be mentioned:
- Changing almost any download options of an active task (including the output directory) will restart the download (!!).
- It is recommended to add the downloads with the desired options or to specify the desired options before starting the download.
- Aria2TUI will only work in a UNIX (linux, macos) environment. If you register your interest I might be able to look into what I would need to change to get it to work on windows.
- Note: This was created for personal use and so some of the code is quite ugly and/or buggy and simply needs to be re-written.
## Similar Projects
- [Ariang](https://github.com/mayswind/AriaNg) A web client for aria2c.
## Support and Feedback
Feel free to request features. Please report any errors you encounter with appropriate context.
Raw data
{
"_id": null,
"home_page": "https://github.com/grimandgreedy/aria2tui",
"name": "aria2tui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "aria2c aria2 downloader listpick tui python curses torrent metalink",
"author": "Grim",
"author_email": "grimandgreedy@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/f8/e3/4b44c062f5c4c66d9acbbfabd7a814cb019250b7491552714cb5bc3f36ee/aria2tui-0.1.10.16.tar.gz",
"platform": null,
"description": "# aria2tui\n\nAria2tui is a TUI download management tool. It acts as a client for the aria2c download utility, facilitating bulk downloading, torrenting, queue control, the fine-tuning of download options (e.g., piece length, user-agent, max speed, etc.), downloading via proxy, and much more. \n\nAria2tui communicates with the aria2c daemon over RPC. The UI is provided by my TUI picker [listpick](https://github.com/grimandgreedy/listpick).\n\n<!-- https://github.com/user-attachments/assets/07ab1f63-3a5e-42dd-bddb-56c948ecd620 -->\n\nhttps://github.com/user-attachments/assets/7c77a13f-90c7-4e67-9946-7b7009c835ad\n\n## Quickstart\n\nInstall aria2tui using pip:\n```bash\npython -m pip install aria2tui\n```\n\nCreate a `config.toml` file and place it in `~/.config/aria2tui/`. Here is the default config:\n\n<!-- ```bash -->\n<!-- mkdir ~/.config/aria2tui/ && -->\n<!-- wget https://raw.githubusercontent.com/grimandgreedy/aria2tui/refs/heads/master/src/aria2tui/data/config.toml -O ~/.config/aria2tui/config.toml -->\n<!-- ``` -->\n\n```toml\n####################################################\n## Default config for Aria2TUI\n## Some common config options have been provided\n## and commented for your convenience\n####################################################\n\n[general]\n\nport = 6800\ntoken = \"1234\"\nurl = \"http://localhost\"\n\n# Used for starting and restarting.\nstartupcmds = [\"aria2c\"]\nrestartcmds = [\"pkill aria2c && sleep 1 && aria2c\"]\n# startupcmds = [\"systemctl --user start aria2d.service\"]\n# restartcmds = [\"systemctl --user restart aria2d.service\", \"notify-send 'Aria2c has been restarted.'\"]\n\n# Used when \"Edit Config\" option is chosen in the main menu\nariaconfigpath = \"~/.config/aria2/aria2.conf\"\n\n# File managers \n## terminal_file_manager will open in the same terminal as Aria2TUI in a blocking fashion;\n## gui_file_manager will fork a new process and open a new application.\nterminal_file_manager = \"yazi\"\ngui_file_manager = \"kitty yazi\"\n\n# Launchers\n## Note that the \"open file(s) (grouped)\" option still requires gio and xdg-mime.\nlaunch_command = \"xdg-open\"\n# launch_command = \"termux-open\"\n\n# Data refresh time (in seconds) for the global stats and for the download data.\nglobal_stats_timer = 1\nrefresh_timer = 2\n\n# Scrolls by default\npaginate = false\n\n[appearance]\ntheme = 3\n\n# Whether the right pane (DL Info, DL graphs) should be displayed by default when opening aria2tui\nshow_right_pane_default = false\n\n# Which pane should be displayed first when the sidebar is opened.\n# [0=DL Files (info), 1=speed graph, 2=progress graph, 3=download pieces]\nright_pane_default_index = 0\n```\n\n**Note**: If you have not used aria2c before then download [this file](https://gist.github.com/qzm/a54559726896d5e6bf21adf2363ad334) and put it in ~/.config/aria2/.\n\nAfter editing ~/.config/aria2tui/config.toml and ensuring that your url, port, and secret token are correct, you are all set to go:\n\n```bash\naria2tui\n```\n\n\nBe aware that Aria2TUI makes use of:\n - `nvim` for viewing/editing download options as well as adding URIs, magnet links and torrent files\n - `xdg-open` and `gio` for determining default applications and opening files.\n\n## Multiple config files\n\nIf you have multiple aria2c daemons you can specify another config file using the ARIA2TUI_CONFIG_PATH environment variable:\n\n```\nARIA2TUI_CONFIG_PATH=/path/to/config/aria2c_torrents.toml aria2tui\nARIA2TUI_CONFIG_PATH=/path/to/config/aria_on_home_server_config.toml aria2tui\n```\n\nIf you wish to use it regularly, then it may be useful to add aliases to your ~/.bashrc.\n```\nalias a2=\"python /path/to/aria2tui/aria2tui.py\"\nalias a2t=\"ARIA2TUI_CONFIG_PATH=/path/to/config/aria2c_torrents.toml aria2tui\"\nalias a2n=\"ARIA2TUI_CONFIG_PATH=/path/to/config/aria_on_home_server_config.toml aria2tui\"\n```\n\n\n## Tips\n\n - Press '?' to see the help page which will list the available keys.\n - If you have problems starting aria2c, check that you have an aria2c config file at ~/.config/aria2/aria2.conf\n - By default aria2tui will track the download that the cursor is on. This is usually what you want. However, sometimes you want to stay at a particular place in the download queue--perhaps you want to remain at the top and watch the currently active downloads.\n - Press ~ and locate the **pin cursor (pc)** option.\n - Note: The pin symbol \ueba0 will be shown in the footer to indicate the cursor tracking mode.\n - If you are performing bulk operations and the downloads are changing state rapidly--e.g., hundreds of images are changing from active/waiting to completed--it is recommended to **toggle the auto-refresh** option to ensure data integrity while selecting which downloads to operate upon.\n - This can be done by either:\n - exiting to the main menu ('q') and going to \"View Downloads\"; or\n - Pressing ~ and toggling auto-refresh.\n - Note: The refresh symbol \uf021 at the top right indicates that you are in auto-refresh mode.\n\n## Other installation options\n\n### Git repo\n\nClone rep\n```bash\ngit clone https://github.com/grimandgreedy/Aria2TUI\n```\n\nCopy config and edit it accordingly:\n```bash\nmkdir ~/.config/aria2tui &&\ncp Aria2TUI/src/aria2tui/data/config.toml ~/.config/aria2tui\n```\nInstall the requirements:\n\n```bash\npython -m pip install -r requirements.txt\n```\n\nNow you can start Aria2TUI:\n```bash\ncd ./Aria2TUI/src\npython -m aria2tui.aria2tui_app\n```\n\n```bash\nalias a2=\"cd /path/to/Aria2TUI/src && python -m aria2tui.aria2tui_app\"\n```\n\n\n## Features\n\n - Dynamic display of downloads\n - View active, queue, errored, stopped\n - Sort/filter/search using regular expressions\n - Add downloads with options\n - Simply dump a list of links;\n - or specify options:\n - proxy\n - User agent\n - ... Many more!\n - See [this section of the aria2c manual](https://aria2.github.io/manual/en/html/aria2c.html#input-file) for all available options all of which are supported\n - Add magnet links and torrent files\n - Operations on downloads:\n - Pause/unpause\n - Remove\n - Change position in queue\n - Open downloaded files\n - Open download location (with yazi)\n - Change download options by value of keys in nvim\n\n - Select download(s) you wish to change the value\n - Change save directory\n - Specify proxy, proxy user, and proxy password\n - Specify user-agent\n - Specify download piece length\n - ... Many more!\n - See [this section of the aria2c manual](https://aria2.github.io/manual/en/html/aria2c.html#input-file) for all available options all of which are supported.\n\n<!-- <div align=\"center\"> <img src=\"assets/change_options.gif\" alt=\"change_options\" width=\"70%\"> </div> -->\n<div align=\"center\"> <img src=\"https://raw.githubusercontent.com/grimandgreedy/aria2tui/refs/heads/master/assets/change_options.gif\" alt=\"change_options\" width=\"70%\"> </div>\n\n - View current options of download\n - Retry download\n - Interact with aria2 daemon\n - Edit config\n - Pause all\n - Restart aria\n - Global and particular download transfer speed *graphs*.\n\n <!-- <div align=\"center\"> <img src=\"assets/transfer_speed_graph.png\" alt=\"speed_graph\" width=\"70%\"> </div> -->\n <div align=\"center\"> <img src=\"https://raw.githubusercontent.com/grimandgreedy/aria2tui/refs/heads/master/assets/transfer_speed_graph.png\" alt=\"speed_graph\" width=\"70%\"> </div>\n\n - Visual options\n - Modify theme\n - '~' to view settings and then select theme\n\n<!-- <div align=\"center\"> <img src=\"assets/themes.png\" alt=\"themes\" width=\"70%\"> </div> -->\n<div align=\"center\"> <img src=\"https://github.com/grimandgreedy/aria2tui/blob/master/assets/themes.png?raw=true\" alt=\"themes\" width=\"70%\"> </div>\n\n - Show/hide columns\n - Press Shift+Column_number to toggle or press '~' to view settings and find the column you wish to toggle.\n - Quick-toggle footer: press '_'\n\n\n## Important\n\nWhile I use Aria2TUI every day, it is still in development and there are many things that still need to be cleaned up.\n\nSome things that should be mentioned:\n\n - Changing almost any download options of an active task (including the output directory) will restart the download (!!). \n - It is recommended to add the downloads with the desired options or to specify the desired options before starting the download.\n - Aria2TUI will only work in a UNIX (linux, macos) environment. If you register your interest I might be able to look into what I would need to change to get it to work on windows.\n - Note: This was created for personal use and so some of the code is quite ugly and/or buggy and simply needs to be re-written.\n\n## Similar Projects\n\n- [Ariang](https://github.com/mayswind/AriaNg) A web client for aria2c.\n\n## Support and Feedback\n\nFeel free to request features. Please report any errors you encounter with appropriate context.\n",
"bugtrack_url": null,
"license": null,
"summary": "aria2tui: A TUI Frontend for the Aria2c Download Manager",
"version": "0.1.10.16",
"project_urls": {
"Bug Tracker": "https://github.com/grimandgreedy/aria2tui/issues",
"Homepage": "https://github.com/grimandgreedy/aria2tui"
},
"split_keywords": [
"aria2c",
"aria2",
"downloader",
"listpick",
"tui",
"python",
"curses",
"torrent",
"metalink"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "04d8976d1c3013db2e568544648875bad6f75db0dba18784e0740b5451f4e853",
"md5": "9a71f1c794b337c4300f124f7bc9f803",
"sha256": "16d135477231f9ea9504a624b8c1a433d5edf15bc64321507e5974a13d100159"
},
"downloads": -1,
"filename": "aria2tui-0.1.10.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a71f1c794b337c4300f124f7bc9f803",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 42865,
"upload_time": "2025-09-14T18:05:36",
"upload_time_iso_8601": "2025-09-14T18:05:36.845342Z",
"url": "https://files.pythonhosted.org/packages/04/d8/976d1c3013db2e568544648875bad6f75db0dba18784e0740b5451f4e853/aria2tui-0.1.10.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f8e34b44c062f5c4c66d9acbbfabd7a814cb019250b7491552714cb5bc3f36ee",
"md5": "c8bde93c5bdcd242625dc9956aee9306",
"sha256": "cfd5eba5351fb2b887b68a94370a76ea1594e609fbc47e9f5786d71c20bd04d0"
},
"downloads": -1,
"filename": "aria2tui-0.1.10.16.tar.gz",
"has_sig": false,
"md5_digest": "c8bde93c5bdcd242625dc9956aee9306",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 2701100,
"upload_time": "2025-09-14T18:05:44",
"upload_time_iso_8601": "2025-09-14T18:05:44.299437Z",
"url": "https://files.pythonhosted.org/packages/f8/e3/4b44c062f5c4c66d9acbbfabd7a814cb019250b7491552714cb5bc3f36ee/aria2tui-0.1.10.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 18:05:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "grimandgreedy",
"github_project": "aria2tui",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "listpick",
"specs": [
[
">=",
"0.1.13.20"
]
]
},
{
"name": "plotille",
"specs": [
[
"==",
"5.0.0"
]
]
},
{
"name": "Requests",
"specs": [
[
"==",
"2.32.4"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"80.9.0"
]
]
},
{
"name": "tabulate",
"specs": [
[
"==",
"0.9.0"
]
]
},
{
"name": "toml",
"specs": [
[
"==",
"0.10.2"
]
]
}
],
"lcname": "aria2tui"
}
JSON
