mox

فارسی

A download manager for the terminal. It splits each file across many connections, resumes after you stop it, and survives flaky networks. It is one Python file and needs nothing outside the standard library.

Install

curl -fsSL https://raw.githubusercontent.com/moxart/moxdl/main/mox.py -o ~/.local/bin/mox && chmod +x ~/.local/bin/mox

It needs Python 3.8 or newer. Or install with pipx:

pipx install moxdl

On Android, in Termux: pkg install python, then the curl line above with $PREFIX/bin/mox in place of ~/.local/bin/mox.

The package is called moxdl; the command is mox.

Speed

Many servers cap the speed of each connection, so more connections means more speed. A 100 MB file from a local server that caps each connection at 4 MB/s:

Some servers gain nothing or refuse extra connections. mox bench URL measures what a server allows and suggests a -c value. It downloads nothing to disk.

Features

• Up to 64 connections per file, 16 by default.
• The progress bar shows which parts of each file are done.
• Fast connections take over work from slow ones.
• Very slow connections are reopened.
• Ctrl+C pauses. Run the same command again, or mox resume, to continue, even after a reboot. A second Ctrl+C quits without waiting for slow connections to close.
• Retries dropped connections, and uses fewer connections when the server refuses more.
• Waits out internet outages, however long, and carries on by itself.
• --watch downloads every file link you copy.
• Scheduled downloads, such as 2:00 to 7:00 every night, and shutting down or sleeping when they end.
• --sort saves videos, music, pictures and so on in their own folders, and episodes of a series in a folder per show and season.
• --quota pauses after a set amount, and the history shows how much was downloaded today and in the last 7 and 30 days.
• A desktop notification, or a Telegram message, when the downloads are done.
• A history of finished downloads, counted by kind: video, audio, images, documents and so on.
• SOCKS5 and HTTP proxies, with user name and password.
• An expired link can be replaced with a fresh one without starting over.
• Starts over if the file on the server has changed.
• A total speed limit, SHA-256 verification, several files at once, URLs from a list file.
• Never overwrites an existing file: a second file.zip becomes file (1).zip.
• Works as a Python library: mox.download(url).

Usage

mox https://example.com/file.iso

Several files, saved to a folder, two at a time:

mox -d ~/Downloads -j 2 https://example.com/a.zip https://example.com/b.zip

A list of URLs, one per line. Blank lines and lines starting with # are skipped:

mox -i links.txt

Limit the total speed:

mox -l 2M https://example.com/big.mkv

A file behind a login, with a cookie from your browser:

mox -H "Cookie: session=abc123" -H "Referer: https://example.com/" https://example.com/private.zip

Check the file against a published checksum:

mox --sha256 9f86d081884c7d65... https://example.com/release.tar.gz

Picking up where you left off

An unfinished download leaves FILE.part and FILE.mox behind. To continue everything unfinished in a folder:

mox resume ~/Downloads

It takes the same options as a normal download, such as -c, -l or --until.

Copy a link, get the file

mox --watch -d ~/Downloads

mox downloads every file link you copy, and skips links to web pages. Ctrl+C stops it.

On Linux it needs wl-paste, xclip or xsel. If your clipboard tool isn't supported, set MOX_CLIPBOARD_COMMAND to a command that prints the clipboard.

History

Every finished download is added to a history. mox history counts them by kind of file:

$ mox history
238 files, 31.4 GB, since 2026-03-02
  image         130    1.2 GB
  video          42   18.3 GB
  ...

It also shows how much was received today and in the last 7 and 30 days, unfinished downloads included, to keep an eye on a data plan. -l also lists the last 20 downloads with where they were saved (-l 50 for more), -k video shows one kind, and --clear erases it all. The history is a text file, ~/.local/share/mox/history.jsonl (%APPDATA%\mox on Windows). Links are saved without their ?query part, where signed links keep their keys.

To leave a download out, use --no-history. To keep no history at all, set MOX_NO_HISTORY=1.

Night downloads

Download between 2:00 and 7:00 every night until everything is done:

mox --at 02:00 --until 07:00 -i links.txt

Leave the terminal open and the computer awake. With only --until, mox stops at that time; run the same command later to continue. With only --at, it waits and then runs to the end.

Add --then shutdown or --then sleep to turn the computer off when everything is done. mox counts down a minute first, so Ctrl+C can still cancel it.

If the internet goes down, mox waits for it as long as it takes, without using up its retries, and continues by itself. It tells an outage from a dead server by also trying 1.1.1.1 and 8.8.8.8. Where those are blocked, set MOX_ONLINE_CHECK to other addresses, such as MOX_ONLINE_CHECK=192.0.2.1:443,198.51.100.7:80.

Data plans

mox --quota 5G -i links.txt

Pauses once 5 GB has come in during this run. Run the same command again to continue. mox history shows what you used today and in the last 7 and 30 days.

Sorting by kind

mox --sort -d ~/Downloads -i links.txt

Puts each file in a folder for its kind inside --dir: Videos, Music, Pictures, Documents, Archives, Programs, Disk images or Subtitles. Files of no known kind stay in --dir.

Episodes of a series go to Series/<show>/Season NN, with their subtitles, the layout Plex, Jellyfin and Kodi expect. mox reads the show and season from the file name: Breaking.Bad.S02E05.720p.mkv goes to Series/Breaking Bad/Season 02. It understands S02E05, 2x05, Season 2 Episode 5, and the Persian فصل ۲ قسمت ۵.

mox resume ~/Downloads finds unfinished downloads in all these folders too.

Notifications

mox --notify --at 02:00 --until 07:00 -i links.txt

--notify sends a desktop notification when the downloads end. For a Telegram message too, make a bot with @BotFather, send it any message, and set:

export MOX_TELEGRAM_TOKEN=123456:ABC...   # from BotFather
export MOX_TELEGRAM_CHAT=987654321        # your chat id, e.g. from @userinfobot

MOX_TELEGRAM_API sets a self-hosted Bot API server instead of api.telegram.org.

Proxies

mox --proxy socks5://127.0.0.1:1080 https://example.com/file.iso
mox --proxy socks5h://user:pass@proxy.example:1080 https://example.com/file.iso
mox --proxy http://127.0.0.1:8080 https://example.com/file.iso

With SOCKS5, the proxy resolves host names. Without --proxy, the http_proxy and https_proxy environment variables apply.

Expired links

If a link expires mid-download, mox prints the command to continue. Get a fresh link and pass the same file name:

mox -d ~/Downloads -o big-file.iso 'https://host.example/new-signed-link'

From Python

pip install moxdl, or drop mox.py next to your script:

import mox

path = mox.download("https://example.com/big.iso", "downloads",
                    progress=lambda done, total: print(f"{done}/{total}"))

Keyword arguments: name, connections, limit (bytes per second, or text such as "2M"), retries, timeout, headers, sha256 and proxy. It returns the saved file's path and raises mox.DownloadError on failure.

Options

Other commands: mox resume [DIR] takes the download options above, except -s. mox history takes -l [N], -k KIND and --clear. mox bench URL takes -s SECONDS per round, -c for the most connections to try, and -t, -H and -x.

Exit codes are 0 when everything finished, 1 when any download failed, 2 for a usage error, 3 when --until or --quota stopped unfinished downloads, and 130 when you pressed Ctrl+C.

Limitations

• HTTP and HTTPS only. No FTP, BitTorrent or Metalink.
• If a server does not support range requests, mox falls back to one connection, and an interrupted download starts over.
• Servers that allow only a few connections waste the first seconds on refusals. Use mox bench to find the right -c.
• HTTP proxies are slower than SOCKS5.
• The schedule only works while mox is running and the computer is awake.
• An existing file with the same name and size counts as already downloaded.
• Not yet tested in Termux or on Windows.

Tests

python3 -m unittest discover -s tests -v

License

MIT. See LICENSE.