Pyload
The free and open-source Download Manager written in pure Python
Install / Use
/learn @pyload/PyloadREADME
Overview
pyLoad is a lightweight, pure-Python download manager with a modern web UI and rich plugin ecosystem. It automates downloads from one-click hosters, cloud drives, and many other sources; supports premium accounts, captcha-solving services, and link decryption; and can run headless on servers, NAS devices, or desktops. Designed for extensibility and low resource usage.
Introduction
- Cross-platform: works on Linux, macOS, and Windows (Python 3.9+)
- Web interface: manage downloads from your browser
- Plugin-driven: hundreds of hosters, decrypters, and addons (notifications, schedulers, extractors, etc.)
Quick Start
Open a terminal window and install pyLoad typing:
pip install --pre pyload-ng[all]
To start pyLoad use the command:
pyload
See the usage section for information on all available options.
If you want to uninstall pyLoad:
pip uninstall pyload-ng
Usage
usage: pyload [-h] [-d] [-r] [--storagedir STORAGEDIR] [--userdir USERDIR]
[--tempdir TEMPDIR] [--dry-run] [--daemon] [--version]
The free and open-source Download Manager written in pure Python
optional arguments:
-h, --help show this help message and exit
-d, --debug enable debug mode
-r, --reset reset default username/password
--storagedir STORAGEDIR use this location to save downloads
--userdir USERDIR use this location to store user data files
--tempdir TEMPDIR use this location to store temporary files
--dry-run test start-up and exit
--daemon run as daemon
--version show program's version number and exit
To start pyLoad, type the command:
pyload
This will create the following directories (if they don't exist already):
~/Downloads/pyLoad: where downloads will be saved.~/.pyload: where user data and configuration files are stored.<TMPDIR>/pyLoad: where temporary files are stored.<TMPDIR>is platform-specific.
Note: On Windows, user data and configuration files are stored in the directory
~\AppData\Roaming\pyLoad.
Help
To show an overview of the available options, type:
pyload --help
Web Interface
Open your web browser and visit the url http://localhost:8000 to have access to the pyLoad's web interface.
- Default username:
pyload. - Default password:
pyload.
It's highly recommended to change the default access credentials on first start.
Advanced Installation
Stable Release
Get the latest stable release of pyLoad:
pip install pyload-ng
Note: No stable release yet, pyLoad is now in pre-release phase.
Available modules
pyload.core: pyLoad's heart.pyload.plugins: the collection of officially supported plugins for pyLoad.pyload.webui: a web interface to interact with pyLoad.
Development Release
You can force the installation of the latest development release of pyLoad,
appending the option --pre to the installation command:
pip install --pre pyload-ng
Do not use development releases in production. Unexpected crashes may occur.
Extra Dependencies
Extra dependencies are non-essential packages that enable additional features of pyLoad.
To install them you have to append a specific tag name to the installation command.
Available tags
plugins: includes packages used by several plugins.build: includes packages used to build translations.all: includes both plugins and build packages.
You can use a tag in this way:
pip install pyload-ng[plugins]
Or group more together:
pip install pyload-ng[plugins][build]
Build Translations
Use the command build_locale to retrieve and build the latest locale files (translations):
python setup.py build_locale
Invoke build_locale before building the package (eg. bdist_wheel).
Note:
You don't need to build the translations if you installed pyLoad through
pip, they're already included.
Development
Set up your development environment
- Clone the repository
- Recommended: create a virtual environment for pyLoad
python3 -m venv .venv
source .venv/bin/activate
- Install pyLoad as editable install
pip install -e .
- Run pyLoad in debug mode
pyload -d
API specification
pyLoad provides an OpenAPI specification for its REST API, visible via Swagger UI under the endpoint
<pyload base url>/api/
The specification file itself is available under
<pyload base url>/api/openapi.json
For reference, there is a local copy of the API specification in openapi-generator/openapi.json.
Based on this file, it is possible to generate client code with the official OpenAPI code generator.
For example, this command will generate a client for Android, using the dockerized generator:
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi-generator/openapi.json \
-g java \
-o /local/openapi-generator/out \
--additional-properties library=retrofit2,serializationLibrary=gson,openApiNullable=false,hideGenerationTimestamp=true,invokerPackage=org.pyload.android.openapi,apiPackage=org.pyload.android.openapi.api,modelPackage=org.pyload.android.openapi.models
If you are developing a client application for pyLoad, you can use this specification to generate a client in any language / framework the OpenAPI generator supports.
The API specification is parsed from the REST API implementation.
The local openapi.json copy should not be edited manually.
Instead, if changes have been made to the API, re-generate the specification file by running
pyload --generate-api-spec
which will update the openapi.json file in place.
Report a Vulnerability
Please refer to SECURITY to read our security policy.
Contribute to pyLoad
Please refer to CONTRIBUTING to read our contribution guidelines.
Docker Images
Available images
Create Container
docker create --name=pyload -v <USERDIR>:/config -v <STORAGEDIR>:/downloads --restart unless-stopped pyload/pyload
Note:
Replace
<STORAGEDIR>with the location on the host machine where you want that downloads will be saved.Replace
<USERDIR>with where you want that user data files (configurations) are stored.
Start Container
docker start pyload
Stop Container
docker stop pyload
Show Logs
docker logs -f pyload
Docker Compose
Compatible with docker-compose v2 schemas:
---
version: '2'
services:
pyload:
image: pyload
build: <REPODIR>
container_name: pyload
environment:
- PUID=1000
- PGID=1000
- TZ=Europe/London
volumes:
- <USERDIR>:/config
- <STORAGEDIR>:/downloads
ports:
- 8000:8000 # Webinterface
- 9666:9666 # Click 'N' Load
restart: unless-stopped
Note:
Replace
<REPODIR>with the location on the host machine where you have checked out the pyload repository.Replace
<STORAGEDIR>with the location on the host machine where you want that downloads will be saved.Replace
<USERDIR>with where you want that user data files (configurations) are stored.
Troubleshooting
pip not found
Retry replacing the command pip with pip3:
pip3 install pyload-ng
If fails again, you may not have the Python interpreter or the pip package manager installed on your system.
Try reinstalling Python to fix this issue.
Visit https://www.python.org/downloads to get the proper Python 3 release for your system.
pyload-ng not found
Check the version of the Python interpreters installed on your system.
To show the version of your default Python interpreter, type the command:
python --version
If the version is too old, try to upgrage Python, then you can retry to install pyLoad.
Python releases below version 3.9 are not supported!
Setuptools is too old
To upgrade the setuptools package, type
Related Skills
node-connect
336.5kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
claude-opus-4-5-migration
82.9kMigrate prompts and code from Claude Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5
frontend-design
82.9kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
model-usage
336.5kUse CodexBar CLI local cost usage to summarize per-model usage for Codex or Claude, including the current (most recent) model or a full model breakdown. Trigger when asked for model-level usage/cost data from codexbar, or when you need a scriptable per-model summary from codexbar cost JSON.
