DEV Community

Smartwa
Smartwa

Posted on

Throttlebuster: Asynchronous Download Accelerator in Python

If you’ve ever wondered why your blazing-fast internet struggles with certain downloads, the answer is usually per-stream throttling. Many CDNs limit the speed of each individual request, but not your entire IP.

So while your browser might cap out at 2 MB/s, tools like IDM (Internet Download Manager) bypass this by opening multiple connections at once.

Now you can do the same in Python. Meet Throttlebuster — an async-first download accelerator that feels like IDM but is fully programmable.

Why Throttlebuster?

  • Concurrent downloads — split files into chunks and fetch them in parallel.
  • Fully async with sync support — integrates into modern async Python apps, or just works in quick scripts.
  • CLI ready — includes a command-line interface (tbust) out of the box.
  • Customizable — hooks for progress bars, retries, headers, proxies, etc.

Whether you’re working with large datasets, video files, or backups, Throttlebuster ensures you use all your bandwidth, not just a single throttled stream.

Installation 

pip install "throttlebuster[cli]"
Enter fullscreen mode Exit fullscreen mode

Developer Usage

Throttlebuster is flexible: you can run it synchronously for quick scripts, or asynchronously with full control.

Example 1: Synchronous Download 

from throttlebuster import DownloadMode, ThrottleBuster

# Create instance with 10 parallel tasks
throttlebuster = ThrottleBuster(tasks=10)

# Run a blocking download
details = throttlebuster.run_sync(
    url="http://localhost:8888/miel-martin.webm",
    mode=DownloadMode.START
)

print(details)
Enter fullscreen mode Exit fullscreen mode

Example 2: Asynchronous Download with Progress Hook 

from throttlebuster import DownloadMode, DownloadTracker, ThrottleBuster

async def callback_function(data: DownloadTracker):
    percent = (data.downloaded_size / data.expected_size) * 100
    print(f"> Downloading {data.saved_to.name} {percent:.2f}%", end="\r")

async def main():
    throttlebuster = ThrottleBuster(tasks=2)
    return await throttlebuster.run(
        "http://localhost:8888/miel-martin.webm",
        progress_hook=callback_function,
        mode=DownloadMode.START
    )

if __name__ == "__main__":
    import asyncio
    details = asyncio.run(main())
    print(details)
Enter fullscreen mode Exit fullscreen mode

CLI Usage

ThrottleBuster also ships with a CLI tool so you can accelerate downloads without writing Python code.

Check available commands:

$ python -m throttlebuster --help
Enter fullscreen mode Exit fullscreen mode

You’ll see commands like:

  • download — Start a download with multiple parallel tasks.
  • estimate — Predict download duration with different task counts.

Download a File 

$ python -m throttlebuster download http://localhost:8888/test.1.opus --tasks 14
Enter fullscreen mode Exit fullscreen mode

or simply:

$ tbust download http://localhost:8888/test.1.opus --tasks 14
Enter fullscreen mode Exit fullscreen mode

Here, --tasks 14 means the file will be split into 14 chunks, each downloaded concurrently.

Estimate Speeds

Want to see how much faster things get as you increase tasks?

$ python -m throttlebuster estimate --url http://localhost:8888/miel-martin.webm 260000
Enter fullscreen mode Exit fullscreen mode

Example output:

       337.88 MB at 260.00 KB/s       
┏━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Tasks ┃ Duration   ┃ Load per task ┃
┡━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ 20    │ 1.08 Mins  │ 16.89 MB      │
│ 10    │ 2.17 Mins  │ 33.79 MB      │
│ 5     │ 4.33 Mins  │ 67.58 MB      │
│ 1     │ 21.66 Mins │ 337.88 MB     │
└───────┴────────────┴───────────────┘
Enter fullscreen mode Exit fullscreen mode

This shows the speed-up effect of adding more concurrent tasks.

Takeaways

  • CDNs throttle per stream, not per IP.
  • Splitting downloads across multiple tasks bypasses this bottleneck.
  • Throttlebuster combines async Python with IDM-like acceleration.
  • Works both in code and as a CLI tool.

👉 Check it out on PyPI or GitHub.

#python #asyncio #downloader #opensource #cli #IDM

Top comments (0)