Configuration Reference (config.json)

May 7, 2026 · View on GitHub

This document provides a comprehensive reference for all configuration options in Youtarr's config.json file. These settings can be changed from the Configuration page in the web UI.

Table of Contents

Configuration File Location

The configuration file is stored at ./config/config.json relative to your Youtarr installation directory.

Auto-Creation

The config.json is automatically created on first startup if it doesn't exist, with sensible defaults from config.example.json.

Editing Configuration

Configuration can be modified through:

  1. Web UI (recommended) - Configuration page in the application
  2. Manual editing - Stop Youtarr, edit the JSON file, restart
  3. Environment variables - Some values can be overridden (see ENVIRONMENT_VARIABLES.md)

Core Settings

Youtube Output Directory (env-only, not a config.json field)

  • Set via: YOUTUBE_OUTPUT_DIR environment variable in .env (see ENVIRONMENT_VARIABLES.md)
  • Type: string
  • Default: "./downloads"
  • Description: Directory path on the host where downloaded videos are stored
  • Note: This setting is not stored in config/config.json. It is displayed read-only in the web UI and can only be changed by editing .env and restarting. Legacy installs that had youtubeOutputDirectory in config.json are automatically migrated to .env during first-run .env bootstrap by scripts/_create-env.sh (i.e. the first time the start script runs with no existing .env).

Enable Automatic Downloads

  • Config Key: channelAutoDownload
  • Type: boolean
  • Default: false
  • Description: Automatically download most recent videos from auto-download enabled channels and tabs
  • Note: When true, the newest videos automatically downloaded on a cron schedule

Download Frequency

  • Config Key: channelDownloadFrequency
  • Type: string (cron expression)
  • Default: "0 * * * *" (hourly)
  • Description: Cron schedule for automatic channel refreshes and downloads
  • Examples:
    • "0 */6 * * *" - Every 6 hours
    • "0 2 * * *" - Daily at 2 AM
    • "0 0 * * 0" - Weekly on Sunday at midnight
    • "*/30 * * * *" - Every 30 minutes

Files to Download per Channel

  • Config Key: channelFilesToDownload
  • Type: number
  • Default: 5
  • Description: Maximum number of most recent videos to download per channel per scheduled auto download
  • Range: 1-10
  • Note: Applies to scheduled autodownloads and manually triggered channel downloads

Channel Videos Hot Load (Infinite Scroll)

  • Config Key: channelVideosHotLoad
  • Type: boolean
  • Default: false
  • Description: When enabled, the channel videos page uses infinite scroll: as you scroll the list, the next page of videos is appended to the accumulated results instead of replacing them. When disabled, the page uses paginated navigation with a fixed page size.
  • Note: Affects the UI only; does not change what gets downloaded.

Preferred Resolution

  • Config Key: preferredResolution
  • Type: string
  • Default: "1080"
  • Options: "4320", "2160", "1440", "1080", "720", "480", "360", "240", "144"
  • Description: Global setting for preferred download resolution
  • Note: Downloads from YouTube at best available quality up to this limit
  • Codec implication: YouTube only provides H.264 in MP4 up to 1080p. Selecting 1440p or 2160p forces Youtarr to pick a VP9 or AV1 source stream (YouTube does not offer H.264 at those resolutions) and remux it into MP4 via --merge-output-format mp4. The remux is lossless (no re-encode), but Plex clients without native VP9/AV1 hardware decode (Apple TV HD, older Apple TV 4K, iOS, older Rokus) will transcode at playback. If direct-play compatibility matters more than resolution, keep this at 1080p or set videoCodec to h264.

Preferred Video Codec

  • Config Key: videoCodec
  • Type: string
  • Default: "default"
  • Options: "default", "h264", "h265"
  • Description: Preferred video codec for downloads. "default" picks the best stream YouTube offers at the requested resolution (typically VP9 or AV1 above 1080p). "h264" forces H.264/AVC, which maximizes client compatibility but effectively caps resolution at 1080p because YouTube does not serve H.264 above that height. "h265" prefers HEVC but YouTube rarely provides it, so it almost always falls back to H.264 MP4.
  • Compatibility:
    • h264: Best compatibility with all devices
    • h265: Better compression, requires modern devices
    • vp9: YouTube's preferred codec
    • av1: Best compression, limited device support

Default Subfolder

  • Config Key: defaultSubfolder
  • Type: string
  • Default: "" (empty - downloads to root directory)
  • Description: Default download location for untracked channels and channels set to use "Default Subfolder"
  • Note: Subfolders are prefixed with __ on the filesystem (e.g., setting Sports creates __Sports/)
  • Channel Subfolder Semantics:
    • "Default Subfolder" (NULL in database): Channel uses this global default setting
    • "No Subfolder" (special value): Channel explicitly downloads to root directory, ignoring the global default
    • Specific subfolder: Channel downloads to that specific subfolder
  • Use Cases:
    • Organize untracked manual downloads into a specific folder
    • Set a default location while allowing individual channels to override
    • Explicitly place specific channels in the root directory using "No Subfolder"

Video Filename Template

  • Config Key: videoFilenamePrefix
  • Type: string
  • Default: "%(uploader,channel,uploader_id).80B - %(title).76B" (matches the legacy fixed format byte-for-byte)
  • Description: User-customizable prefix for downloaded video filenames AND per-video directory names. Youtarr always appends [VIDEO_ID].EXT to filenames and - VIDEO_ID to per-video folder names so it can re-find your videos on disk; those suffixes are not configurable.
  • Syntax: Uses yt-dlp's output template syntax. Common tokens: %(title)s, %(uploader)s, %(channel)s, %(upload_date>%Y-%m-%d)s, %(channel_id)s, %(display_id)s. Use .NB to byte-truncate values (e.g. %(title).76B) or .Ns for character truncation (e.g. %(title).40s); recommended to keep paths under Windows' 260-char limit.
  • Validation: Empty values, path separators (/, \), .., ASCII control characters, values longer than 160 characters, malformed yt-dlp percent syntax, and invalid truncation like %(title).40 are rejected. Escape literal percent signs as %%. Trailing whitespace is trimmed on save.
  • Scope: Global setting. Applies only to NEW downloads; existing files are not renamed.
  • Examples (all paired with the locked suffixes):
    • Default: Preston - ESCAPING 99 Nights in the Forest IN REAL LIFE! [Cbq15X05wyY].mp4
    • Date prefix (%(upload_date>%Y-%m-%d)s - %(title).76B): 2025-10-17 - ESCAPING 99 Nights ... [Cbq15X05wyY].mp4
    • Plex YouTube-Agent (%(upload_date>%Y_%m_%d)s %(title).76B): 2025_10_17 ESCAPING 99 Nights ... [Cbq15X05wyY].mp4 (compatible with Absolute-Series-Scanner and YouTube-Agent.bundle)
    • Title only (%(title).76B): ESCAPING 99 Nights ... [Cbq15X05wyY].mp4
  • UI: A live preview in Settings -> Core Settings -> File Structure Settings shows the rendered folder and file names against a sample video, with length warnings (yellow > 110 chars, red > 130 chars on the rendered name).

Enable Subtitles

  • Config Key: subtitlesEnabled
  • Type: boolean
  • Default: false
  • Description: Download subtitles/closed captions with videos

Subtitle Languages

  • Config Key: subtitleLanguage
  • Type: string
  • Default: "en"
  • Description: Preferred subtitle language(s) when downloading subtitle files for videos (ISO 639-1 code)
  • Examples: "en" (English), "es" (Spanish), "fr" (French)
  • Note: Only displayed when subtitles are enabled

Dark Mode

  • Config Key: darkModeEnabled
  • Type: boolean
  • Default: false
  • Description: Enable dark mode in web UI

Plex Integration

Plex API Key

  • Config Key: plexApiKey
  • Type: string
  • Default: "" (empty)
  • Description: Plex authentication token (X-Plex-Token)
  • Note: Can be obtained through Plex OAuth in the web UI or manually entered

Plex YouTube Library ID

  • Config Key: plexYoutubeLibraryId
  • Type: string
  • Default: "" (empty)
  • Description: Default Plex library section ID for YouTube videos. Used for all downloads that do not match a per-subfolder mapping (see below).
  • Note: Library refresh is automatically triggered if configured when new videos are downloaded

Plex Subfolder Library Mappings

  • Config Key: plexSubfolderLibraryMappings
  • Type: Array<{ subfolder: string | null, libraryId: string }>
  • Default: [] (empty — all downloads use the default library above)
  • Description: Maps channel subfolders to specific Plex library IDs, enabling different subfolders to refresh different Plex libraries after a download.
  • Usage: Configured via the web UI under Plex Media Server Integration → Per-Subfolder Library Mappings once connected to Plex.
  • Format: Each entry specifies a subfolder (the clean name without the __ filesystem prefix, or null for the root/no-subfolder case) and the target libraryId.
  • Example: 
    "plexSubfolderLibraryMappings": [
  { "subfolder": "kids", "libraryId": "2" },
  { "subfolder": "music", "libraryId": "3" },
  { "subfolder": null, "libraryId": "1" }
]
  • Fallback: Any subfolder not listed here will fall back to plexYoutubeLibraryId.

Plex IP

  • Config Key: plexIP
  • Type: string
  • Default: "" (empty)
  • Description: Plex server IP address or hostname
  • Examples: "192.168.1.100", "host.docker.internal"

Plex Port

  • Config Key: plexPort
  • Type: string
  • Default: "32400"
  • Description: Plex server port number

Use HTTPS for Plex

  • Config Key: plexViaHttps
  • Type: boolean
  • Default: false
  • Description: Use HTTPS for Plex connections
  • Note: Enable for remote Plex servers or when SSL is configured

Plex URL Override

  • Config Key: plexUrl
  • Type: string
  • Default: "" (empty)
  • Description: Optional full Plex base URL (e.g., https://plex.example.com:32400)
  • Usage: Not configurable via the web UI. Edit config/config.json manually or set the PLEX_URL environment variable to populate it.
  • Note: When this field is set it takes precedence over the plexIP, plexPort, and plexViaHttps values shown in the UI.

YouTube Data API (Optional)

YouTube API Key

  • Config Key: youtubeApiKey
  • Type: string
  • Default: "" (empty)
  • Description: Optional YouTube Data API v3 key. When set, Youtarr uses the API for faster channel metadata, video metadata, and search fetches. On any failure (invalid key, quota exhausted, API disabled, network error), Youtarr silently falls back to yt-dlp with no user-visible error.
  • Notes:
    • API keys do not expire. The configuration page shows "last validated" timestamp instead of an expiration.
    • Default quota is 10,000 units per day per Google Cloud project, resetting at midnight Pacific time. Search calls cost 100 units; metadata and channel/playlist calls cost 1 unit per call.
    • On a 403 quotaExceeded response, Youtarr enters an in-memory cooldown until the next Pacific-midnight reset and uses yt-dlp exclusively during that window.
    • When a key is configured, channel video listing and tab auto-detection use the API for all three tabs (Videos, Shorts, Streams) via the per-tab auto-generated playlist IDs (UULF/UUSH/UULV). yt-dlp remains the fallback.
    • Search results filter out live/upcoming broadcasts and Shorts under 60s to match yt-dlp's behavior. The Shorts filter requires a follow-up videos.list enrichment call to read each result's duration; if that enrichment fails (e.g., quota burned mid-search), the search returns the un-enriched results and a small number of Shorts may slip through. Live/upcoming filtering still applies in that fallback path.
    • Set up instructions and a test button are in the Configuration page under Integrations.

SponsorBlock Settings

Enable SponsorBlock

  • Config Key: sponsorblockEnabled
  • Type: boolean
  • Default: false
  • Description: Enable SponsorBlock to skip/remove sponsored segments

SponsorBlock Action

  • Config Key: sponsorblockAction
  • Type: string
  • Default: "remove"
  • Options: "remove", "mark"
  • Description: How to handle sponsored segments
    • remove: Cut segments from video file
    • mark: Add chapters to mark segments

SponsorBlock Categories

  • Config Key: sponsorblockCategories
  • Type: object
  • Default:
{
  "sponsor": true,
  "intro": false,
  "outro": false,
  "selfpromo": true,
  "preview": false,
  "filler": false,
  "interaction": false,
  "music_offtopic": false
}
  • Description: Which segment types to skip/remove

SponsorBlock API URL

  • Config Key: sponsorblockApiUrl
  • Type: string
  • Default: "" (uses default SponsorBlock API)
  • Description: Custom SponsorBlock API server URL (optional)
  • Example: "https://sponsor.ajay.app"

Kodi, Emby and Jellyfin Compatibility

Write Channel Posters

  • Config Key: writeChannelPosters
  • Type: boolean
  • Default: true
  • Description: Generate channel poster images for media servers
  • Note: Creates poster.jpg in each channel directory

Write Video NFO Files

  • Config Key: writeVideoNfoFiles
  • Type: boolean
  • Default: true
  • Description: Generate NFO metadata files for Kodi/Jellyfin/Emby
  • Note: Creates .nfo XML files with video metadata

Enable Cookies

  • Config Key: cookiesEnabled
  • Type: boolean
  • Default: false
  • Description: Use cookies for YouTube authentication
  • Note: May be required in some cases to get around YouTube bot detection

Custom Cookies Uploaded

  • Config Key: customCookiesUploaded
  • Type: boolean
  • Default: false
  • Description: Indicates if custom cookies.txt file has been uploaded
  • Note: Managed automatically by the application

Notifications

Youtarr uses Apprise to send notifications when new videos are downloaded, supporting 100+ notification services.

Enable Notifications

  • Config Key: notificationsEnabled
  • Type: boolean
  • Default: false
  • Description: Enable notifications when new videos are downloaded

Apprise URLs

  • Config Key: appriseUrls
  • Type: array of objects
  • Default: [] (empty array)
  • Description: List of notification service configurations

Each entry in the array is an object with the following properties:

PropertyTypeDescription
urlstringApprise-compatible notification URL
namestringFriendly name for this notification (e.g., "Discord - Gaming Server")
richFormattingbooleanEnable rich formatting (embeds, styled text) when supported

Example Configuration:

{
  "appriseUrls": [
    {
      "url": "discord://webhook_id/webhook_token",
      "name": "Discord Server",
      "richFormatting": true
    },
    {
      "url": "tgram://bot_token/chat_id",
      "name": "Telegram Group",
      "richFormatting": true
    },
    {
      "url": "ntfy://my-topic",
      "name": "Ntfy Mobile",
      "richFormatting": false
    }
  ]
}

Rich Formatting

For supported services, Youtarr sends beautifully formatted notifications with embeds, styled text, video cards, and timestamps. Services without rich formatting support receive plain text notifications.

ServiceURL FormatRich Formatting
Discorddiscord://webhook_id/webhook_token✅ Embeds with colors, thumbnails
Telegramtgram://bot_token/chat_id✅ HTML formatting
Slackslack://token_a/token_b/token_c✅ Block Kit formatting
Emailmailto://user:pass@gmail.com✅ HTML email with styling
Pushoverpover://user_key@app_token❌ Plain text
Ntfyntfy://topic❌ Plain text
Other servicesVarious❌ Plain text

Toggle "Rich formatting" off on any webhook to send plain text instead.

Supported Services

Apprise supports 100+ notification services. See the Apprise Notification Services Wiki for a complete list and URL formats.

Common services include:

  • Discord: discord://webhook_id/webhook_token
  • Telegram: tgram://bot_token/chat_id
  • Slack: slack://token_a/token_b/token_c
  • Pushover: pover://user_key@app_token
  • Ntfy: ntfy://topic or ntfys://your-server/topic
  • Email: mailto://user:pass@gmail.com
  • Matrix: matrix://user:pass@hostname/#room
  • Gotify: gotify://hostname/token

Migration from Discord Webhook

If you previously used the discordWebhookUrl configuration option, Youtarr automatically migrates it to the new appriseUrls format on startup:

Before (legacy):

{
  "discordWebhookUrl": "https://discord.com/api/webhooks/123/abc",
  "notificationService": "discord"
}

After (automatic migration):

{
  "appriseUrls": [
    {
      "url": "https://discord.com/api/webhooks/123/abc",
      "name": "Discord Webhook",
      "richFormatting": true
    }
  ]
}

The old discordWebhookUrl and notificationService fields are automatically removed after migration. No manual action is required.

Download Performance

Download Socket Timeout

  • Config Key: downloadSocketTimeoutSeconds
  • Type: number
  • Default: 30
  • Description: Network timeout for download connections (seconds)
  • Range: 10-300
  • Note: Corresponds to yt-dlp --socket-timeout setting. Time to wait before giving up, in seconds.

Download Throttled Rate

  • Config Key: downloadThrottledRate
  • Type: string
  • Default: "100K"
  • Description: Bandwidth limit for downloads
  • Examples: "500K", "1M", "10M", "" (unlimited)
  • Note: Corresponds to yt-dlp --throttled-rate setting. Minimum download rate in bytes per second below which throttling is assumed and the video data is re-extracted.

Download Retry Count

  • Config Key: downloadRetryCount
  • Type: number
  • Default: 2
  • Description: Number of retry attempts for failed downloads
  • Range: 0-10
  • Note: Used for yt-dlp --fragment-retries and --retries settings.

Enable Stall Detection

  • Config Key: enableStallDetection
  • Type: boolean
  • Default: true
  • Description: Detect and abort stalled downloads
  • Note: Setting to control whether stall detection window and rate threshold are used.

Stall Detection Window

  • Config Key: stallDetectionWindowSeconds
  • Type: number
  • Default: 30
  • Description: Time window for stall detection (seconds)

Stall Detection Rate Threshold

  • Config Key: stallDetectionRateThreshold
  • Type: string
  • Default: "100K"
  • Description: Minimum download rate before considering stalled

Sleep Between Requests

  • Config Key: sleepRequests
  • Type: number
  • Default: 1
  • Description: Delay between YouTube API requests (seconds)
  • Note: Corresponds to yt-dlp --sleep-requests setting.

Advanced Settings

Proxy

  • Config Key: proxy
  • Type: string
  • Default: "" (empty)
  • Description: HTTP/HTTPS proxy for downloads
  • Format: "http://proxy:port" or "socks5://proxy:port"
  • Note: The proxy is used by yt-dlp for all YouTube requests (downloads, metadata, thumbnails). Some operations like thumbnail downloads and RSS feed checks first attempt a direct HTTP request with a 15-second timeout before falling back to yt-dlp. SOCKS5 proxy users may notice brief delays (~15 seconds) during these fallbacks when adding or refreshing channels, but the operations will complete successfully via yt-dlp.

IP Family

  • Config Key: ytdlpIpFamily
  • Type: string (one of "ipv4", "ipv6", "auto")
  • Default: "ipv4"
  • Description: IP family preference applied to every yt-dlp invocation.
    • "ipv4" adds -4 (force IPv4) — recommended for YouTube reliability and the historical default.
    • "ipv6" adds -6 (force IPv6).
    • "auto" adds neither flag and lets the OS decide.
  • Note: Force IPv6 or Auto can make YouTube downloads less reliable. Use only if your network requires it.

Download Rate Limit

  • Config Key: ytdlpDownloadRateLimit
  • Type: string
  • Default: "" (empty — no limit)
  • Description: Maximum download rate, passed to yt-dlp as --limit-rate. Format: digits with optional decimal and optional K/M/G suffix (e.g. "5M", "500K", "1.5M"). Empty disables the limit.

Custom yt-dlp Arguments

  • Config Key: ytdlpCustomArgs
  • Type: string
  • Default: "" (empty)
  • Description: Free-form yt-dlp arguments appended to every invocation. Tokenized shell-style (single/double quotes and backslash-escapes supported). Maximum length: 2000 characters.
  • Blocked flags: For safety, several flags are rejected at save time and silently dropped at command-build time. The full list is in server/modules/download/customArgsParser.js; it includes (among others) --exec, --netrc-cmd, -o/--output, -P/--paths, --print-to-file, --external-downloader/--downloader, --external-downloader-args/--downloader-args, --cookies/--cookies-from-browser, --ffmpeg-location, --config-location, --batch-file, --load-info-json, --download-archive, plus the flags that have dedicated config fields (--proxy, -4/-6, --limit-rate, --sleep-requests).
  • Order: Custom args are appended LAST in the yt-dlp command, after Youtarr's managed flags. Per yt-dlp's last-wins semantics, your flags can override managed ones (e.g. --retries 5 overrides Youtarr's default --retries 2).
  • Note: Power-user feature. Incorrect flags can prevent downloads from working entirely or break Youtarr's behavior in unexpected ways. Use the "Validate Arguments" button in the UI to argparse-check your args against yt-dlp before saving. The validation does not gate save — invalid args can still be saved and will only surface failures at download time.

Use External Temporary Directory

  • Config Key: useTmpForDownloads
  • Type: boolean
  • Default: false
  • Description: Controls where downloads are staged before moving to final location:
    • false (default): Downloads are staged in a hidden .youtarr_tmp/ directory within your output folder. Uses fast atomic renames since source and destination are on the same filesystem. The dot-prefix hides in-progress downloads from media servers like Plex and Jellyfin.
    • true: Downloads are staged in the external path specified by tmpFilePath (e.g., /tmp). Useful when your output directory is on slow network storage and you want to download to fast local storage first.
  • Note: Some managed platforms (e.g., ElfHosted) force this value on.

External Temporary File Path

  • Config Key: tmpFilePath
  • Type: string
  • Default: "/tmp/youtarr-downloads"
  • Description: External temporary directory for downloads when useTmpForDownloads is true
  • Note: Only used when useTmpForDownloads is enabled. Internal path in Youtarr container.

NFS Output Directory Considerations

If your output directory (YOUTUBE_OUTPUT_DIR) is on an NFS mount, be aware of the following:

When useTmpForDownloads: true: Downloads are staged on a different filesystem from the output directory. The move from temp to output is a cross-filesystem copy+delete, which is vulnerable to NFS stale mount errors. If the NFS mount goes stale, downloads succeed to the temp dir but fail during the move phase. Critically, yt-dlp marks the video as "downloaded" in its archive before the move, so the video becomes permanently stuck — it won't be retried on the next scheduled run because yt-dlp thinks it already succeeded.

Recommended NFS mount options: If using NFS, mount with options that prevent stale file handles:

server:/export /mnt/nfs-output nfs hard,intr,actimeo=3,timeo=300,retrans=5 0 0
  • hard — retries NFS operations indefinitely instead of failing immediately
  • intr — allows signals to interrupt hung NFS operations
  • actimeo=3 — refreshes NFS attribute cache every 3 seconds (default 60s can cause stale metadata)
  • timeo=300,retrans=5 — longer timeouts before declaring failure

Docker native NFS volumes (recommended): Instead of bind-mounting a host NFS directory, let Docker mount NFS directly. This is more resilient because Docker manages the NFS connection rather than inheriting a potentially-stale host mount:

services:
  youtarr:
    volumes:
      - youtube-data:/usr/src/app/data        # named NFS volume
      - ./server/images:/app/server/images
      - ./config:/app/config
      - ./jobs:/app/jobs

volumes:
  youtube-data:
    driver: local
    driver_opts:
      type: nfs
      o: addr=YOUR_NFS_SERVER_IP,hard,intr,nfsvers=4,actimeo=3
      device: ":/path/to/your/nfs/export"

Simplest workaround: Set useTmpForDownloads: false (the default). Downloads are staged inside the output directory itself, so the move is a same-filesystem rename — atomic and immune to this class of error. Note: if the NFS mount is stale, downloads will still fail, but they will fail before yt-dlp marks them as archived — so they'll be automatically retried on the next scheduled run rather than getting permanently stuck.

Auto-Removal Settings

Enable Auto-Removal

  • Config Key: autoRemovalEnabled
  • Type: boolean
  • Default: false
  • Description: Enable automatic deletion of old videos

Free Space Threshold

  • Config Key: autoRemovalFreeSpaceThreshold
  • Type: string
  • Default: null (not set)
  • Description: Minimum free space to maintain
  • Examples: "100GB", "500GB", "1TB"
  • Note: Deletes oldest videos when space falls below threshold

Video Age Threshold

  • Config Key: autoRemovalVideoAgeThreshold
  • Type: string
  • Default: null (not set)
  • Description: Delete videos older than this age
  • Examples: "30d" (30 days), "3m" (3 months), "1y" (1 year)

API Keys & External Access

Settings for API key authentication used by bookmarklets, mobile shortcuts, and automation tools.

API Key Rate Limit

  • Config Key: apiKeyRateLimit
  • Type: number
  • Default: 10
  • Description: Maximum download requests per minute per API key
  • Range: 1-100
  • Note: Helps prevent abuse from external integrations. Each API key is rate-limited independently.

For detailed information on creating and using API keys, see API Integration Guide.

yt-dlp Auto-Update

Youtarr can optionally check for and install yt-dlp updates on a nightly schedule. The toggle and its status display live next to the manual yt-dlp update button on the Core Settings page.

Auto-Update Enabled

  • Config Key: autoUpdateYtdlp
  • Type: boolean
  • Default: false
  • Description: When true, Youtarr runs yt-dlp -U at 4:00 AM (server local time, controlled by the TZ env var) every night.
  • Behavior:
    • The update is skipped while any download job is in progress and is retried the next night.
    • If the update process itself fails (e.g., permission denied on managed platforms, network error, timeout), the failure is logged and Youtarr continues to run on the previous yt-dlp version.
    • On success, the in-process yt-dlp version cache is refreshed without requiring a server restart.

Last Checked Timestamp

  • Config Key: ytdlpLastChecked
  • Type: string | null (ISO 8601 timestamp)
  • Default: null
  • Description: Set automatically every time the nightly job runs (regardless of outcome). Surfaced in the UI as "Last checked: ...".
  • Note: Managed by the application; do not edit by hand.

Last Updated Timestamp

  • Config Key: ytdlpLastUpdated
  • Type: string | null (ISO 8601 timestamp)
  • Default: null
  • Description: Set automatically when the nightly job successfully installs a new yt-dlp version. Not updated when the check finds yt-dlp is already current.
  • Note: Managed by the application; do not edit by hand.

Last Run Result

  • Config Key: ytdlpLastResult
  • Type: object | null
  • Default: null
  • Shape: { status: 'updated' | 'up-to-date' | 'skipped' | 'error', message?: string, version?: string }
  • Description: Records the outcome of the most recent nightly run. The UI uses this to render an inline status next to "Last checked".
  • Statuses:
    • updated — a new version was installed; version holds the new version string.
    • up-to-date — yt-dlp was already current.
    • skipped — the run was deferred (for example, a download was in progress); message describes why.
    • error — yt-dlp -U failed; message holds a short error description.
  • Note: Managed by the application; do not edit by hand.

Filesystem Rescan

For user-facing documentation on when and how to use the filesystem rescan (moving files, converting formats, supported extensions), see Rescan Files on Disk.

Last Rescan Result

  • Config Key: rescanLastRun
  • Type: object | null
  • Default: null
  • Shape: 
    {
  "startedAt": "2026-05-04T15:13:00.000Z",
  "completedAt": "2026-05-04T15:14:32.000Z",
  "trigger": "manual | scheduled | startup",
  "status": "completed | timed-out | error",
  "videosUpdated": 12,
  "videosMarkedMissing": 3,
  "videosScanned": 8421,
  "filesFoundOnDisk": 8423,
  "errorMessage": null
}
  • Description: Records the outcome of the most recent filesystem reconciliation pass (the backfillVideoMetadata run). Written by the daily cron, the server-startup pass, and the manual "Rescan files on disk" action on the Maintenance settings page. Surfaced read-only on that page so users can see when the last scan ran and what it found or fixed.
  • Note: Managed by the application; do not edit by hand.

Account & Security

username

  • Type: string
  • Default: Not set (must be configured)
  • Description: Login username for the web interface
  • Validation: 1-32 characters, no leading/trailing spaces
  • Note: Set during initial setup or via AUTH_PRESET_USERNAME environment variable

passwordHash

  • Type: string
  • Default: Not set (must be configured)
  • Description: Bcrypt hash of the login password
  • Note: Never edit directly - use web UI or AUTH_PRESET_PASSWORD environment variable

System Fields

These fields are managed automatically by the application:

uuid

Type: string Default: Auto-generated Description: Unique installation identifier Note: Currently unused

Configuration Examples

See config/config.example.json

Best Practices

  1. Backup your config.json before major changes
  2. Use the Web UI for configuration when possible
  3. Test cron expressions at crontab.guru
  4. Monitor disk space when enabling auto-downloads
  5. Start conservative with download frequency to avoid rate limiting

Troubleshooting

Configuration Not Saving

  • Check file permissions: ls -la config/config.json
  • Ensure proper ownership matches YOUTARR_UID/GID
  • Check logs for write permission errors

Missing Configuration Options in UI

  • Clear browser cache
  • Ensure you're running the latest version
  • Check browser console for JavaScript errors

Downloads Not Running on Schedule

  • Verify cron expression syntax
  • Check timezone setting (TZ environment variable)
  • Review logs for scheduler errors