putioarr
Proxy that allows put.io to be used as a download client for sonarr/radarr/whisparr. The proxy uses the Transmission protocol.
Installation
There are a few ways to install putioarr:
Cargo
Make sure you have a proper rust installation
cargo install putioarr
Usage
First, generate a config using putio generate-config. This will generate a config file in ~/.config/putioarr/config.toml. Use -c to override the configuration file location.
Edit the configuration file and make sure you configure the username and password, as well as the sonarr/radarr/whisparr details.
- Run the proxy:
putioarr run - Configure the Transmission download client in sonarr/radarr/whisparr:
- Url Base: /transmission
- Username:
- Password:
Docker
Docker images are based on linuxserver.io images.
Usage
The first time you run your docker container, run it without the -d option, since you'll need a put.io API key. When no configuration is found, it will present you a link and a code that will generate an API key. After the key is generated, putioarr will write a default config in your config volume (see docker compose and docker cli below). Modify the config (like username, password and sonarr/radarr/whisparr configuration) in order to properly use putioarr.
Supported Architectures
We utilise the docker manifest for multi-platform awareness.
Simply pulling ghcr.io/wouterdebie/putioarr:latest should retrieve the correct image for your arch (amd64 or arm64).
docker-compose (recommended, click here for more info)
---
version: "2.1"
services:
putioarr:
image: ghcr.io/wouterdebie/putioarr:latest
container_name: putioarr
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
volumes:
- /path/to/putioarr/config:/config
- /path/to/your/downloads:/downloads
ports:
- 9091:9091
restart: unless-stopped
docker cli (click here for more info)
Parameters
Container images are configured using parameters passed at runtime (such as those above). These parameters are separated by a colon and indicate <external>:<internal> respectively. For example, -p 8080:80 would expose port 80 from inside the container to be accessible from the host's IP on port 8080 outside the container.
| Parameter | Function |
|---|---|
-p 9091 |
Port connecting to putioarr |
-e PUID=1000 |
for UserID - see below for explanation |
-e PGID=1000 |
for GroupID - see below for explanation |
-e TZ=Etc/UTC |
specify a timezone to use, see this list. |
-v /config |
putioarr configs |
-v /downloads |
torrent download directory |
Behavior
The proxy will upload torrents or magnet links to put.io. It will then continue to monitor transfers. When a transfer is completed, all files belonging to the transfer will be downloaded to the specified download directory. The proxy will remove the files after sonarr/radarr/whisparr has imported them and put.io is done seeding. The proxy will skip directories named "Sample".
Configuration
A configuration file can be specified using -c, but the default configuration file location is:
- Linux: ~/.config/putioarr/config.toml
- MacOS: ~/Library/Application Support/nl.evenflow.putioarr
TOML is used as the configuration format:
# Required. Username and password that sonarr/radarr/whisparr use to connect to the proxy
username = "myusername"
password = "mypassword"
# Required. Directory where the proxy will download files to. This directory has to be readable by
# sonarr/radarr/whisparr in order to import downloads
download_directory = "/path/to/downloads"
# Optional bind address, default "0.0.0.0"
bind_address = "0.0.0.0"
# Optional TCP port, default 9091
port = 9091
# Optional log level, default "info"
loglevel = "info"
# Optional UID, default 1000. Change the owner of the downloaded files to this UID. Requires root.
uid = 1000
# Optional polling interval in secs, default 10.
polling_interval = 10
# Optional skip directories when downloding, default ["sample", "extras"]
skip_directories = ["sample", "extras"]
# Optional number of orchestration workers, default 10. Unless there are many changes coming from
# put.io, you shouldn't have to touch this number. 10 is already overkill.
orchestration_workers = 10
# Optional number of download workers, default 4. This controls how many downloads we run in parallel.
download_workers = 4
# Optional. When false (default), locally downloaded files are deleted after
# the *arr imports them. Set to true to keep them in download_directory instead
# (put.io transfers/files are still cleaned up).
keep_downloads = false
# Optional, default false. When true, archives (put.io type ARCHIVE: RAR parts,
# zip, 7z) are downloaded too, for an extractor such as Unpackerr pointed at
# download_directory -- see "Archives (Unpackerr integration)" below.
download_archives = false
[putio]
# Required. Putio API key. You can generate one using `putioarr get-token`
api_key = "MYPUTIOKEY"
# Both [sonarr] and [radarr] are optional, but you'll need at least one of them
[sonarr]
url = "http://mysonarrhost:8989/sonarr"
# Can be found in Settings -> General
api_key = "MYSONARRAPIKEY"
# Optional: Download to a category-specific subdirectory (e.g., /downloads/tv/)
# category = "tv"
[radarr]
url = "http://myradarrhost:7878/radarr"
# Can be found in Settings -> General
api_key = "MYRADARRAPIKEY"
# Optional: Download to a category-specific subdirectory (e.g., /downloads/movies/)
# category = "movies"
[whisparr]
url = "http://mywhisparrhost:6969/whisparr"
# Can be found in Settings -> General
api_key = "MYWHISPARRAPIKEY"
# Optional: Download to a category-specific subdirectory (e.g., /downloads/adult/)
# category = "adult"
Archives (Unpackerr integration)
By default, putioarr only downloads video and audio files. Archives (put.io type
ARCHIVE: multi-volume RAR releases with .rar/.r00/.r01/... parts, .zip,
.7z) are skipped. A transfer that contains only archives stays on put.io, and
putioarr logs a warning, since the *arr has nothing to import.
Set download_archives = true to download archives like any other file and
leave them to an extractor, typically
Unpackerr, set up for the same
download_directory. putioarr considers an archive done once either:
- it is gone from disk (e.g. with Unpackerr's
delete_orig), or - the *arr reports importing a file from inside the transfer's own folder (the extracted video).
A transfer that is a single archive file, not in a folder, only counts as done once the archive is gone from disk.
Only enable this if you run an extractor pointed at the same download
directory; otherwise the archives sit there until import_timeout_secs is
reached.
Category-based Download Directories
To prevent Sonarr/Radarr/Whisparr from seeing each other's downloads, you can configure separate download directories using categories:
-
In putioarr's config.toml, add a
categoryfield to each service:[] = "tv" [] = "movies" -
In Sonarr/Radarr/Whisparr's download client settings, set the same category in the Transmission configuration.
-
Downloads will then be organized into subdirectories:
- Sonarr downloads →
/download_directory/tv/ - Radarr downloads →
/download_directory/movies/ - Whisparr downloads →
/download_directory/adult/
- Sonarr downloads →
This feature ensures each *arr application only sees and processes its own downloads.
Connecting Sonarr/Radarr/Whisparr
putioarr pretends to be a Transmission client, so you add it in the *arr just like a real Transmission instance.
In Settings → Download Clients → Add → Transmission, set:
| Field | Value |
|---|---|
| Host | the host running putioarr (e.g. putioarr if on the same Docker network, or its IP) |
| Port | 9091 (or your configured port) |
| URL Base | /transmission |
| Username | the username from your config |
| Password | the password from your config |
| Category | the category for this *arr, if you set one (e.g. tv for Sonarr, movies for Radarr) — must match the category in putioarr's config |
Click Test; it should turn green. Then Save.
Repeat for each *arr, using that *arr's category.
Important — same download path in both containers. The *arr imports a completed download by reading the files from disk itself, and putioarr only cleans up once it finds that import in the *arr's history under its own path. So the *arr must see the files putioarr downloaded at the same path: mount the same host directory into both containers at the same place (e.g.
/downloadsin putioarr and/downloadsin Sonarr/Radarr), and setdownload_directoryto that path. A Remote Path Mapping in the *arr is not a substitute: the *arr will import, but it records the import under its own path, so putioarr never sees it and never cleans up the local files or the put.io transfer.
Troubleshooting
Downloads finish, but nothing is imported and the files stay in
download_directory.
This is almost always a path problem: the *arr can't find the files putioarr
downloaded because it's looking at a different path (or doesn't have the volume
mounted at all). The *arr's Activity → Queue usually shows a warning for the
download. Make sure the download directory is mounted into both containers at
the same path — see Connecting Sonarr/Radarr/Whisparr above — and confirm the
*arr can list the files there. putioarr leaves the files alone until it sees
the import. After import_timeout_secs (2 hours by default) it logs "still not
imported … giving up watching" and stops checking that download.
Downloads are imported, but the files stay in download_directory and on
put.io.
putioarr didn't recognize the import. The usual cause is a Remote Path Mapping
or a different mount path in the *arr, so the *arr records the import under
a path putioarr doesn't know. Use the same path in both containers instead.
The download client tests fine but grabs never appear on put.io.
Check that the *arr is sending grabs to putioarr (the Activity → Queue in the
*arr) and watch putioarr's logs — every grab logs an "uploaded" line. Make sure
the [putio] api_key is valid (regenerate with putioarr get-token).
Downloads go to the wrong folder / one *arr imports another's downloads.
Set a distinct category per *arr in putioarr's config and the matching
Category in each *arr's Transmission settings. See Category-based Download
Directories above.
Nothing happens / no logs. Raise the log level with loglevel = "debug" in
the config to see what putioarr is doing.
TODO:
- Figure out a better way to map a transfer to a completed import. Since a transfer can contain multiple files (e.g. a whole season) we currently check if all video files have been imported. Most of the time this is fine, except when there are sample videos. sonarr/radarr/whisparr will not import samples, but will make no mention of the fact that the sample was skipped. Right now we check against the
skip_directorieslist, which works, but might be tedious. - Automatically pick the right putio proxy based on speed
Thanks
Thanks to davidchalifoux for borrowed code from kaput-cli.