pyLoad

Lightweight Python download manager with web interface

pyLoad is a free, open-source download manager written in Python, designed to be extremely lightweight and easily extensible. It supports downloading from one-click hosters, container formats (DLC, CCF, RSDF), and video sites through its plugin system—all fully manageable via a modern web interface.

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find pyLoad in the catalog (browse Download Clients or search), and click Install. The dashboard sets up the isolated Python virtual environment automatically, streams the install log live, and pyLoad appears in your Application Control panel when it finishes. Reinstall, Update, and Remove are available from the same panel.

What you see and can manage is gated by your account: admins manage any user’s apps; regular users manage their own. For the full package flow see App Management.

Install from the CLI (automation)

The CLI runs the same install and is suited to automation and scripting:

qb install pyload -u username

Directory Layout

Network & Access

pyLoad runs on an auto-assigned port (default 8001) and is accessible through the nginx reverse proxy:

https://yourserver.com/username/pyload/

Default credentials:

• Username: Your QuickBox username
• Password: pyload (change immediately after first login)

Services

pyLoad uses a templated systemd unit (pyload@.service) running as a forking daemon:

# Check status
systemctl status pyload@username
 
# View logs
journalctl -u pyload@username -f
 
# Restart service
systemctl restart pyload@username

VPN routing

pyLoad can route all of its download traffic through a VPN tunnel using QuickBox Pro’s app-scoped routing, with either a WireGuard or an OpenVPN backend. When routing is enabled, every fetch pyLoad makes to a one-click hoster exits through the VPN peer instead of your server’s real IP.

Why route pyLoad: one-click hosters see and log the IP that requests each download, and they enforce their limits against it: wait timers between files, daily download caps, and outright blocks on datacenter IP ranges. Routing pyLoad through a VPN hides the server’s real IP behind the provider’s exit, and switching to a different VPN server gives you a fresh exit IP that resets those per-IP limits.

pyLoad is a per-user template service (pyload@<user>), so several users can each route their own instance independently, the same as Emby, Jellyfin, and qBittorrent. It appears in the App-Scoped Routing card once pyLoad is installed and its service is running; there is no pre-install staging.

How to enable VPN routing for pyLoad:

1. Go to System > VPN Control (/system/vpn) in the dashboard
2. Upload at least one WireGuard .conf or OpenVPN .ovpn file if you have not done so already
3. Scroll to the App-Scoped Routing card on the VPN Control page
4. Select pyLoad from the app list
5. Choose the tunnel backend and a peer configuration from the dropdown
6. Click Enable Routing

pyLoad restarts inside its VPN network namespace and its downloads exit through the VPN peer from that point forward. The web interface keeps working: pyLoad binds to loopback inside the namespace, and QuickBox routes the dashboard proxy to it automatically, so the https://yourserver.com/username/pyload/ URL and dashboard tile are unaffected.

The default kill-switch stale threshold for pyLoad is 30 minutes, matching qBittorrent and the other downloaders. pyLoad runs long, chunked downloads, so a shorter window risks tearing down routing and aborting an in-progress download during a brief VPN handshake stall. You can adjust it between 60 seconds and 24 hours on the app row inside the App-Scoped Routing card.

For full details on routing configuration, kill switch settings, and live metrics, see the VPN Control dashboard page.

Best Practices

Additional Resources