Skip to content

Configuration

upPollo is configured through a single config.yaml. The example config documents every option inline and is always up to date — this page covers how the config file is found, managed, and migrated, plus an overview of each section.

File locations

upPollo searches for config.yaml in this order:

  1. the path given via --config / -c (highest priority),
  2. the current working directory (. or ./configs),
  3. the executable's directory (or its configs/ subdirectory),
  4. the user config directory: ~/.config/upPollo/config.yaml.

A config.yaml that belongs to another tool (e.g. rePollo's) is skipped and left untouched. If no config exists, a default one is generated at ~/.config/upPollo/config.yaml on first run.

upPollo config generate                       # write default config to the user config dir
upPollo config generate /path/to/config.yaml  # or to a custom location
upPollo -c /path/to/config.yaml upload ...    # use a custom config for any command

Validating

upPollo config validate
upPollo config validate -c /path/to/config.yaml

This verifies YAML syntax and required fields, tests connectivity to the configured services — the active torrent client, all enabled Radarr/Sonarr instances, and cross-seed — and prints a summary of your configuration.

Config migration

New upPollo versions occasionally introduce new config options. The migration system adds them to your file automatically with their default values, at any nesting depth, without ever touching your existing settings. A backup (config.yaml.backup) is written before every change:

cp ~/.config/upPollo/config.yaml.backup ~/.config/upPollo/config.yaml  # restore if needed

Migration runs automatically whenever the config is loaded. You can also run it manually, e.g. after editing the file or to force a rewrite:

upPollo config migrate           # add any missing options
upPollo config migrate --force   # rewrite even when nothing new is detected

Legacy formats are migrated too: a single tracker: section from old versions is moved to trackers.rhd automatically. If migration fails (e.g. file permissions), a warning is logged and upPollo continues with your existing config.

The migrated config is written to a temporary file in the same directory and then renamed over config.yaml, so upPollo processes that start at the same time (e.g. several uploads triggered right after an update) always read a complete file. This needs write access to the config directory, and the file keeps its permissions. A config without any settings (empty or only comments) is not migrated, so it can't overwrite your backup.

Section overview

The sections below follow the order of the example config.

Logging

logging:
    level: "info"        # "debug" for verbose output
    directory: "./logs"  # daily log files (YYYY-MM-DD.log), CLI and API mode
    loki: ...            # optional log shipping, see the Loki guide

See Loki logging for the loki block.

Metadata API keys

tmdb_api_key: ""  # TMDb v3 API key, required
tvdb_api_key: ""  # TVDb v4 API key, needed for series
mal_client_id: "" # MyAnimeList API client ID, used for AnimeWorld uploads

tmdb_api_key is required: every release is identified through TMDb. tvdb_api_key provides the TVDb ID and the episode air dates for the release date filter on series uploads. mal_client_id lets upPollo look up the MyAnimeList ID that AnimeWorld uploads include. How to get the keys and what happens without them is described in Getting started: TMDb, TVDb, MyAnimeList.

General settings

Option Description
mkbrr_workers Limit torrent-creation workers (some seedboxes need this; 0 = auto)
name_similarity, size_similarity Thresholds for dupe detection — keep the defaults unless you know what you're doing
fuzzy_score_cutoff Below this confidence of a TMDb title search, upPollo asks for confirmation (in unattended mode the release is skipped). An ID found in the NFO, the Matroska tags, on XREL, SRRDB or CrowdNFO is checked against the release name separately, see How a release is identified
upload_signature Text appended to upload descriptions; a release group can replace it with its own
seed_on_dupe, seed_on_dupe_match Seed the existing torrent when a dupe is found — see Seed on dupe
temp_directory Custom temp dir (useful on shared machines where /tmp is restricted)
save_torrent_dir Also save the .torrent created for the first tracker that accepted the upload here, named after the release (empty = disabled)
link_mode hardlink (default), symlink, or copy — see Media library integration
allow_source_modification Let scene verification rename the release folder and its files and replace NFOs in your source folder — see Source protection
path_mapping Translate paths when your torrent client runs on a remote machine

Trackers

default_tracker: "rhd"  # "rhd" or "aw"; override per upload with --tracker
trackers:
    rhd:
        api_key: ""       # from your RocketHD profile
        announce_url: ""  # from the RocketHD upload page
        base_url: "https://rocket-hd.cc/"
    aw:
        api_key: ""
        announce_url: ""
        base_url: "https://animeworld.cx/"

Release groups

Register your own group names so uploads are flagged as personal releases (and optionally internal on a home tracker) automatically — see Release groups.

Torrent clients

Select the client with torrent_client: "qbittorrent", "rtorrent", "deluge", or "transmission". Only the matching section needs to be filled in.

All clients share these options:

Option Description
download_folder Where upPollo links/copies files before seeding, as seen by the machine running upPollo (empty = don't)
skip_client Don't add the created torrent to the client (e.g. when autobrr does it)
hash_check When to hash-check added torrents: "always", "never", or "ondupe" (only when seed on dupe triggers). The --check-hash flag always forces a check. Only qBittorrent and Deluge v2 can skip the check; for rTorrent, Transmission and Deluge v1 the setting has no effect
category Default category/label (overridden by --category)

Client specifics:

  • qBittorrent — host, and either user/pass or api_key (qBittorrent 5.2.0+, generated under Options → Web UI → Generate API key; if set, it takes precedence and user/pass are ignored). Also: basic_user/basic_pass for a reverse proxy with HTTP basic auth, insecure_skip_verify, tags (default tags), and reuse_hash (look for an existing torrent with matching files in qBittorrent before re-hashing).
  • rTorrent — host is the XMLRPC endpoint (e.g. http://localhost/RPC2 or an httprpc plugin URL), plus basic_user/basic_pass and insecure_skip_verify.
  • Deluge — host, port (daemon port, default 58846), user/pass, and version ("v1" for 1.3.x, "v2" for 2.0+).
  • Transmission — host (RPC URL), user/pass, insecure_skip_verify, and tags (applied as labels).

Screenshots

screenshots:
    custom_ffmpeg_path: ""  # optional, see the Custom FFmpeg guide
    num: 4
    services:               # tried in "order" until one succeeds
        - name: "ptscreens"
          api_key: ""
          enabled: true
          order: 1
        - name: "imgbb"
          api_key: ""
          enabled: false
          order: 2
        - name: "imgbox"    # no API key required
          enabled: false
          order: 3
    parallel_uploads: 1     # screenshots uploaded at the same time

num sets how many screenshots end up in the description. upPollo takes one more and drops the smallest, running one ffmpeg process per screenshot at the same time, at most 8 and no more than the CPU cores available to upPollo. A 2160p HDR screenshot takes up to about 1 GB of memory per process, so the default num: 4 needs up to about 5 GB and num: 7 or more up to about 8 GB.

An enabled ptscreens or imgbb entry needs an api_key, otherwise the config is rejected. Where to get the keys and each host's size limit is listed in Getting started: Screenshot hosts.

parallel_uploads defaults to 1: the screenshots are uploaded one after another, with a 200 ms pause between them. Set it to num to upload all of them at once. With four screenshots and a host that needs 800 ms per image, that takes 0.8 s instead of 3.8 s; on a slow uplink the gain is smaller, since the images still share it. The description keeps the screenshot order, and a host that answers with HTTP 429 is retried as in the sequential mode. Keep 1 if your host rate-limits bursts of uploads.

On RocketHD the upload does not wait for the screenshots. upPollo uploads the torrent with the description minus the screenshots as soon as it is hashed, and replaces the description through the tracker API once the screenshots are hosted. In API mode the screenshots are taken while the torrent is hashed, and the next queued upload does not wait for them (see API mode: Throughput). In the CLI they are taken after the upload, unless an AnimeWorld upload earlier in the same run needed them already; then RocketHD gets them right away. Until the update the torrent page shows no screenshots. With several trackers in one run, the update follows the last upload.

A screenshot error that is known before the RocketHD upload stops it, as on AnimeWorld. One that comes after the upload leaves the torrent on the tracker, and the upload still counts as done: upPollo warns with the torrent ID. If only the update fails, the warning comes with the finished description, which you paste on the site. You can edit your upload there as long as it is not approved, and for 24 hours after the upload. AnimeWorld has no such API and waits for the screenshots before its upload.

For HDR content on machines with limited ffmpeg builds, see Custom FFmpeg.

CrowdNFO

Optionally upload MediaInfo, NFO, and hash metadata to CrowdNFO. upload_on controls when ("always" or only on "success"); max_hash_size limits hashing for large releases (-1 = never hash, 0 = no limit). In API mode the submission runs after the upload has finished, so the next queued upload does not wait for the hash, see API mode: Throughput.

Media server (Radarr/Sonarr)

Query Radarr/Sonarr to upload renamed library files under their original release names — see Media library integration.

Auto-update

See Getting started: Automatic updates.

API

Settings for upPollo serve — see API mode. On HDD or NAS storage with upload_workers above 1, set disk_concurrency: 1, so only one upload at a time hashes or otherwise reads whole files, see API mode: Throughput.

Upload filters

Automatically skip releases by language, quality, group, tags, or release date — see Upload filters.