pyLoad
The pyLoad
About pyLoad
pyLoad is an open-source download manager designed for always-on devices like home servers, NAS systems, and routers. It supports various file hosts, container formats, and web standards, enabling fully automated, unattended downloads. With its web interface, pyLoad allows for easy remote management from any device.
How you can use this integration
The pyLoad integration allows you to monitor and control your downloads directly from Home Assistant. Here are some ways you can use it:
- Track active downloads – Send a notification when all downloads are complete or if the queue is empty.
- Free space alerts – Set up an automation to alert you when disk space is low, ensuring downloads don’t fail due to storage issues.
- Pause downloads – Automatically pause downloads when streaming or gaming to avoid bandwidth congestion, then resume them later.
Prerequisites
To set up the pyLoad integration, you must have a running pyLoad instance on your home server, NAS, or any other device. An always-on device is recommended. Ensure that pyLoad’s web interface is accessible for Home Assistant.
If you haven’t set up pyLoad yet, an easy way to get it up and running is by installing the pyLoad-ng add-on for Home Assistant
- During the setup process in Home Assistant, you will need:
- pyLoad account credentials – A valid username and password to authenticate with pyLoad.
- The hostA device that participates in your network. If asked for the host, enter either the device’s IP address or host name. If you don’t know those, check the list of hosts in your router. [Learn more]
of the device running pyLoad. - The port number that pyLoad is listening on (default is usually
8000
).
The account used for integration must either be an admin account or one with at least the following permissions: DELETE
, STATUS
, LIST
, and MODIFY
. You can set up and manage users and permissions under Settings -> Users in the pyLoad web interface.
Configuration
To add the pyLoad service to your Home Assistant instance, use this My button:
Manual configuration steps
If the above My button doesn’t work, you can also perform the following steps manually:
-
Browse to your Home Assistant instance.
-
In the bottom right corner, select the
Add Integration button. -
From the list, select pyLoad.
-
Follow the instructions on screen to complete the setup.
Configuration parameters
If checked, the SSL certificate will be validated to ensure a secure connection.
Sensors
- Speed: Monitors the current download speed.
- Active downloads: Indicates the number of files pyLoad is actively downloading
- Downloads in queue: Shows the number of downloads currently in the queue.
- Finished downloads: Indicates the number of completed downloads.
- Free space: Shows the available disk space in the download directory.
Buttons
- Abort all running downloads: Aborts all currently running downloads.
- Delete finished files/packages: Deletes all finished files and packages.
- Restart all failed files/packages: Restarts all failed downloads.
- Restart pyLoad core: Restarts the pyLoad core.
Switches
- Pause/Resume Queue: Pauses or resumes the download queue. When paused, active downloads will continue, but new downloads in the queue will not start.
- Auto-reconnect: If configured, enables pyLoad to automatically reconnect the internet connection.
Automations
Get started with these example automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more].
Pause downloads when disk space is low
This automation will pause new downloads when your available disk space falls below 5 GB.
Example YAML configuration
alias: "Monitor pyLoad download queue"
description: "Pause new downloads when the disk space is low."
triggers:
- trigger: numeric_state
entity_id: sensor.pyload_free_space
below: 5000000000 # Trigger when free space drops below 5 GB (in bytes)
actions:
- action: switch.turn_off
target:
entity_id: switch.pyload_pause_resume_queue
- service: notify.persistent_notification
data:
message: "Free space is low, pausing pyLoad queue."
mode: single
Halt pyLoad downloads when watching Netflix
This automation halts all active pyLoad downloads when watching Netflix on your media player.
Example YAML configuration
alias: "Halt pyLoad downloads when watching Netflix"
description: "Halt all pyLoad downloads when Netflix streaming starts on the media player."
triggers:
- trigger: state
entity_id: media_player.android_tv
to: playing
conditions:
- condition: state
entity_id: media_player.android_tv
attribute: app_id
state: com.netflix.ninja
actions:
- action: button.press
target:
entity_id: button.pyload_abort_all_running_downloads
- action: notify.persistent_notification
data:
message: "pyLoad downloads have been halted because Netflix streaming started."
mode: single
Data updates
This integration pollsData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more] your pyLoad instance every 20 seconds. If you prefer a different update frequency, you can define a custom polling interval — see Defining a custom polling interval for details.
Known limitations
- Paused downloads: When the download queue is paused, active downloads will continue, but new downloads in the queue will not start until the queue is resumed.
-
Halt all downloads: To completely halt downloading, use the
Abort all running downloads
action. TheRestart failed files/packages
action will also resume any aborted downloads.
Troubleshooting
In any case, when reporting an issue, please enable debug logging, restart the integration, and as soon as the issue reoccurs, stop the debug logging again (download of debug log file will start automatically). Further, if still possible, please also download the diagnostics data. If you have collected the debug log and the diagnostics data, provide them with the issue report.
Remove integration
This integration can be removed by following these steps:
To remove an integration instance from Home Assistant
- Go to Settings > Devices & services and select the integration card.
- From the list of devices, select the integration instance you want to remove.
- Next to the entry, select the three-dot
menu. Then, select Delete.