Configuration

There are two ways to configure YT-DLP WebUI:

.env file — server-level settings (port, HTTPS, admin credentials, rebranding)
WebUI UI settings — download preferences (folders, concurrent downloads, rate limits)

📄 The `.env` File

The .env file sits in the project root directory and contains settings that are loaded when the server starts. Any changes require a server restart.

How to set it up

# Copy the example file
cp .env.example .env

# Edit with any text editor
nano .env

All `.env` Variables

🏷️ App Settings

Variable	Default	What it does
`APP_NAME`	`YT-DLP WEB`	Changes the app name shown in the navigation bar, page titles, and footer
`APP_LOGO_ICON`	`icon-download`	The SVG icon displayed next to the app name (pick from icons in base.html)
`APP_FAVICON`	SVG data URI (download arrow)	The icon that appears in browser tabs
`APP_SECRET_KEY`	`change-me-in-production-use-random-string`	🔑 Important: Used to sign session cookies. Set a random string in production

Rebranding Example

Want to call it “My Downloader” instead?

APP_NAME="My Downloader"
APP_LOGO_ICON="icon-play"        # Must be an icon ID from base.html
APP_FAVICON="https://example.com/favicon.ico"

💡 Available icons: icon-download, icon-home, icon-play, icon-settings, icon-history, icon-monitor, icon-system, icon-trash, icon-cancel, icon-retry, etc.

🌐 Server Settings

Variable	Default	What it does
`PORT`	`8000`	Which port the web server listens on
`USE_SSL`	`false`	Set to `true` to enable HTTPS
`SSL_CERT_FILE`	`ssl/cert.pem`	Path to your SSL certificate file
`SSL_KEY_FILE`	`ssl/key.pem`	Path to your SSL key file

Enabling HTTPS

# 1. Edit .env
USE_SSL=true

# 2. Generate a self-signed certificate
mkdir -p ssl
openssl req -x509 -newkey rsa:4096 -keyout ssl/key.pem \
  -out ssl/cert.pem -days 365 -nodes -subj '/CN=localhost'

# 3. Restart the server
./run.sh

Now access your app at https://localhost:8000.

🔒 For production, use a certificate from Let’s Encrypt instead of a self-signed one.

👤 Auth Settings

Variable	Default	What it does
`ADMIN_USERNAME`	`admin`	The default admin account username
`ADMIN_PASSWORD`	`admin123`	⚠️ Change this in production! The admin account password

On first startup, if no users exist in the database, the app automatically creates an admin account using these credentials.

🗄️ Database Settings

Variable	Default	What it does
`DB_PATH`	`app/data/ytdlp.db`	Where the SQLite database file is stored

📝 Logging Settings

Variable	Default	What it does
`LOG_PATH`	`logs/ytdlp-web.log`	Where log files are written
`LOG_LEVEL`	`INFO`	How detailed logs are: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
`LOG_MAX_BYTES`	`10485760`	Max size of a single log file (10MB) before rotation
`LOG_BACKUP_COUNT`	`5`	How many old log files to keep

🖥️ Web UI Settings

These are managed from Settings → Downloads in the app. They’re stored in the database — no file editing needed.

Download Settings

Setting	Default	What it does
`output_dir`	`downloads`	Where downloaded files are saved
`max_concurrent_downloads`	`3`	How many downloads can run at the same time
`rate_limit`	(empty)	Speed limit (e.g., `1M` = 1 MB/s, `500K` = 500 KB/s)
`subtitle_lang`	`en`	Subtitle language(s) to download (e.g., `en,es,fr`)
`embed_thumbnail`	`false`	Embed the video thumbnail in the output file
`embed_metadata`	`false`	Embed metadata (title, upload date, etc.) in the file
`container_preference`	(empty)	Preferred container format: `mkv`, `mp4`, or `webm`
`auto_update`	`manual`	yt-dlp auto-update: `manual`, `daily`, or `weekly`
`download_archive`	(empty)	Path to an archive file (tracks downloaded URLs to skip repeats)
`show_thumbnails`	`true`	Show video thumbnails in the job list on the dashboard

Proxy Settings

Setting	What it does
`http_proxy`	HTTP proxy URL (e.g., `http://proxy:8080`)
`socks_proxy`	SOCKS proxy URL (e.g., `socks5://proxy:1080`)

Organization Settings

Setting	What it does
`folder_template`	Template for organizing downloads (default: `downloads/{domain}/{date}`)
`organize_by_domain`	Group downloads by source domain (YouTube, Vimeo, etc.)
`organize_by_date`	Group downloads by date

File Management

Setting	Default	What it does
`cookie_file_path`	(empty)	Path to a cookies.txt file for accessing private/age-restricted content

🔐 Complete HTTPS Guide

Option 1: Self-Signed Certificate (quick and easy)

# Set in .env
USE_SSL=true

# Generate certificate
mkdir -p ssl
openssl req -x509 -newkey rsa:4096 -keyout ssl/key.pem \
  -out ssl/cert.pem -days 365 -nodes -subj '/CN=localhost'

# Restart
./run.sh

Your browser will show a “Not Secure” warning — this is normal for self-signed certs. Click “Advanced” → “Proceed” to continue.

Option 2: Let’s Encrypt (production)

For a proper trusted certificate, use a reverse proxy (like Nginx or Caddy) with Let’s Encrypt in front of the app.

🌓 Theme

There’s no manual theme setting — the UI automatically follows your operating system’s dark/light mode. Switch your system theme and the app follows along.

📤 Exporting & Importing Settings

You can backup or migrate all settings (including custom presets) as a JSON file:

Export: Settings → Export → saves a .json file
Import: Settings → Import → upload a previously exported .json file

Great for:

Moving to a new server
Sharing your setup
Keeping a backup before major changes

📄 The .env File