Invidious Configuration Options: A Complete Guide to Server and User Settings

Invidious uses a single YAML configuration file (config/config.yml) to define all server-level settings, database connections, feature toggles, and default user preferences, which are parsed at startup into a global CONFIG constant accessible throughout the application.

All Invidious configuration options live in one central location. The application reads these settings from config/config.yml (falling back to config/config.example.yml) without requiring recompilation. According to the src/invidious/config.cr source file, the parsed structure is stored in a singleton CONFIG object that controls everything from PostgreSQL connections to the default video quality for new visitors.

Core Server Settings

The core settings manage how the Invidious instance connects to infrastructure, exposes itself to the network, and handles background processing.

Database Connection

You must define PostgreSQL connection details using either a structured db block or a single database_url string. The db block accepts user, password, host, port, and dbname parameters.

db:
  user: kemal
  password: kemal
  host: localhost
  port: 5432
  dbname: invidious

Alternatively, provide a full connection URI:

database_url: postgres://user:pass@localhost:5432/invidious

These options are referenced in config/config.example.yml and parsed by the configuration loader in src/invidious/config.cr.

Network Binding and Ports

Control inbound HTTP server behavior with:

• port: Internal port the HTTP server listens on (default: 3000)
• external_port: Public-facing port for reverse proxy setups (e.g., 443)
• host_binding: IP address to bind to (use 0.0.0.0 for all interfaces)
• domain: Public domain name serving the instance
• https_only: Force HTTPS redirection (true/false)
• hsts: Enable HTTP Strict Transport Security headers
• socket_binding: Optional Unix socket path for local reverse proxies

Outbound Connectivity and Proxying

Manage how Invidious connects to YouTube and external APIs:

• disable_proxy: Globally disable proxying for YouTube requests
• pool_size: Connection pool size per YouTube host (default: 100)
• http_proxy: Structured block defining host and port for API calls
• force_resolve: Force IPv4 or IPv6 resolution (ipv4, ipv6, or unset)
• cookies: Extra request cookies sent to YouTube

The networking implementation in src/invidious/yt_backend/connection_pool.cr checks these values when establishing outbound connections.

Logging Configuration

Control application verbosity:

• output: Destination (STDOUT or file path)
• log_level: Verbosity level (All, Trace, Debug, Info, Warn, Error, Fatal)
• colorize_logs: Boolean to enable terminal color codes (true/false)

Feature Toggles

Enable or disable major UI components and functionality:

• popular_enabled: Show/hide the "Popular" feed tab
• statistics_enabled: Expose the /api/v1/stats endpoint
• registration_enabled: Allow new account creation
• login_enabled: Allow existing user authentication
• captcha_enabled: Require captcha for registration
• enable_user_notifications: Enable server-wide notification system

Background Job Configuration

Tune the background workers that refresh channels and feeds:

• channel_threads: Number of threads for channel crawlers
• channel_refresh_interval: How often to refresh channels (e.g., 30m, 1h)
• full_refresh: Boolean to force complete metadata refreshes
• feed_threads: Threads for feed updaters
• jobs: Sub-configuration to enable/disable specific jobs:
  • clear_expired_items
  • refresh_channels
  • refresh_feeds

Each job under jobs accepts an enable: true/false flag.

Security and Miscellaneous

Critical security settings include:

• hmac_key: Secret key for CSRF protection and signature generation (must be a random 20+ character string)
• admins: Array of admin email addresses with elevated privileges
• dmca_content: Array of video IDs where the download widget is blocked
• playlist_length_limit: Maximum number of videos allowed in user playlists (default: 500)
• modified_source_code_url: URL to your fork's source code (GPL compliance)
• banner: HTML string injected into the top of every page
• use_pubsub_feeds: Enable PubSubHubbub for real-time subscription updates
• cache_annotations: Cache legacy YouTube annotations

Default User Preferences

The default_user_preferences: block defines the experience for visitors without personal preference cookies. These values are applied globally and can be overridden per-user via the UI or /preferences endpoint. According to config/config.example.yml, key options include:

Interface and Localization:

• locale: UI language code (e.g., en-US, de)
• region: Content localization ISO-3166 country code (e.g., US)
• dark_mode: Theme setting (dark, light, auto)
• thin_mode: Hide thumbnails in listings (true/false)
• feed_menu: Array defining tab order (["Popular","Trending","Subscriptions","Playlists"])
• default_home: Landing page feed (Popular, Trending, etc.)
• max_results: Items per page for Invidious-generated listings

Video Playback:

• quality: Default format (dash, hd720, medium, small)
• quality_dash: Default DASH quality when quality: dash (auto, best, 4320p, etc.)
• speed: Playback speed multiplier (0.25 to 2.0)
• volume: Default volume level (0-100)
• autoplay: Auto-play videos on page load
• continue / continue_autoplay: Auto-play next video after current ends
• video_loop: Loop video continuously
• vr_mode: Enable 360° video playback
• listen: Default to audio-only playback
• preload: HTML5 video preload attribute
• save_player_pos: Remember playback position per video
• local: Proxy videos through the instance by default

Content Display:

• captions: Array of three preferred caption languages (e.g., ["English", "Spanish", ""])
• annotations / annotations_subscribed: Show legacy YouTube annotations
• comments: Two-element array defining comment sources (["youtube", "reddit"] or empty)
• player_style: Player UI variant (invidious or youtube)
• related_videos: Show sidebar recommendations
• extend_desc: Expand video descriptions by default
• show_nick: Display logged-in username in UI

Subscription Feed Behavior:

• unseen_only: Show only unwatched videos
• notifications_only: Show only videos with notifications
• latest_only: Show latest videos only
• sort: Subscription sort order (published, etc.)
• automatic_instance_redirect: Auto-redirect to random instance when clicking "switch instance"

How Configuration Is Loaded

The loading process defined in src/invidious/config.cr follows three steps:

1. Startup Parsing: The application reads config/config.yml using YAML::Parser, falling back to config/config.example.yml if the primary file is missing.

2. Global Singleton: The parsed structure is stored in a global CONFIG constant, allowing any file (such as src/invidious/yt_backend/connection_pool.cr checking CONFIG.http_proxy) to access settings via CONFIG.<option>.

3. Runtime Updates: When administrators update server-wide settings via the /preferences endpoint, the handler in src/invidious/routes/preferences.cr writes the new YAML back to disk using File.write("config/config.yml", CONFIG.to_yaml) and updates the in-memory CONFIG object immediately.

The src/invidious/user/preferences.cr file defines the schema used to validate user preference updates against the default_user_preferences structure.

Practical Configuration Examples

Minimal Production Configuration

Create config/config.yml with these essential values:

# Database connection

db:
  user: kemal
  password: kemal
  host: localhost
  port: 5432
  dbname: invidious

# Network binding

port: 3000
host_binding: 0.0.0.0
domain: example.com
https_only: true

# Enable features

popular_enabled: true
registration_enabled: true
login_enabled: true

# Security

hmac_key: "CHANGE_ME_TO_20_PLUS_RANDOM_CHARS"

# Default user experience

default_user_preferences:
  locale: en-US
  region: US
  dark_mode: auto
  quality: dash
  quality_dash: auto
  autoplay: false
  local: true

Place this file at config/config.yml and restart the Invidious service. Any omitted options inherit defaults from the built-in schema.

Checking Configuration at Runtime

The CONFIG object provides helper methods for checking feature states:

# In src/invidious/config.cr

def disabled?(feature : String) : Bool
  # Returns boolean based on configuration

end

# Usage in route handlers:

if CONFIG.disabled?("downloads")
  # Hide download button from UI

end

Summary

• Invidious configuration is controlled by a single YAML file at config/config.yml, parsed into a global CONFIG constant defined in src/invidious/config.cr.
• Database connections support either structured db blocks or database_url strings for PostgreSQL.
• Network settings include port, host_binding, domain, and https_only for reverse proxy setups.
• Feature toggles like registration_enabled, popular_enabled, and statistics_enabled control UI availability without code changes.
• The default_user_preferences block sets the initial experience for anonymous visitors, covering localization, video quality, autoplay behavior, and feed settings.
• Background job threads and intervals are tunable via channel_threads, channel_refresh_interval, and the jobs sub-tree.
• Changes to config/config.yml take effect immediately without recompiling the Crystal application.

Frequently Asked Questions

Where does Invidious store its configuration file?

Invidious reads configuration from config/config.yml in the application root directory. If this file is missing, it falls back to config/config.example.yml. The configuration is parsed at startup by src/invidious/config.cr and stored in a global CONFIG singleton.

What is the difference between the db block and database_url?

The db configuration uses separate keys for user, password, host, port, and dbname, making credentials easier to manage in containerized environments. The database_url accepts a single PostgreSQL URI string (e.g., postgres://user:pass@host/db). You must use one or the other, not both.

How do I disable user registration while keeping login enabled?

Set registration_enabled: false while keeping login_enabled: true in config/config.yml. This prevents new account creation while allowing existing users to authenticate. You may also set captcha_enabled: true to add friction to any registration attempts if using alternative registration methods.

How do I set the default video quality for all users?

Under the default_user_preferences: block, set quality: dash for adaptive streaming, or use hd720, medium, or small for fixed resolutions. When using DASH, specify quality_dash: auto (bandwidth-based) or a specific resolution like 1080p. These values apply to all visitors until they manually change preferences in the UI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}