Download settings

Configure download helpers and policies

Applies to 2026.10.19. Use this page to locate existing download settings; use download recovery to troubleshoot a failed job.

Choose the setting in the right place

1. In Settings, use Cookies for the shared cookie file, Extractor for API/concurrency controls, and yt-dlp for extractor update/configuration options.
2. Open the source's Edit form for its Cookie Behaviour, player client, availability rules and profile. Switch to Advanced editing mode if needed.
3. Save changes, then check the next indexing or download job. Provider requirements still apply; changing a setting does not grant access to restricted media.

Available controls

• Upload, paste, and inspect the shared cookies.txt file in Settings.
• Test a YouTube API key before using it for indexing.
• Distinguish unavailable, removed, ignored, filtered, and policy-blocked media.
• Review failed downloads and retry one item or a group.
• Keep a durable prevention or error reason: manual, policy, or error, plus whether a failure is transient or permanent.
• Use Retry Now for transient failures. Force Retry can attempt a permanent failure. On Home > Failed, filter by All, Transient, or Permanent failures.
• Treat YouTube rate limits and similar bot-challenge responses as transient, not as a permanent download block.
• Select stable, nightly, frozen-nightly, fallback, or pinned yt-dlp update policies.
• Maintain extra yt-dlp options through Settings.
• Configure source-specific cookie behavior where authentication requirements differ.
• Use media profiles for format, naming, subtitles, SponsorBlock, and related download choices.
• Preserve structured error text and queue state for diagnostics and retry workflows.
• Optionally complete downloads on local disk, then transfer finished files to the media library. See DOWNLOAD_STAGING_PATH in Environment Variables.
• Optionally send yt-dlp through a bgutil-compatible PO-token provider. See POT_PROVIDER_URL in Environment Variables and Diagnostics.

Staging and worker configuration

Environment variables override saved worker limits while set. Leave them unset when you want to control workers through Settings. See Environment variables.

With staging unset, initial downloads write directly to the media library. Replacements of existing files are staged separately to keep the old file playable; see replacement safety.

Related guides

• Source settings for locks, posters, player clients and availability.
• Retention and protection for independent cutoff and age-based cleanup.
• Notifications for Apprise and optional video titles.
• All feature guides.