Getting Started

Get YT-DLP WebUI up and running in under 5 minutes. This guide assumes you have basic familiarity with the terminal.

📋 What You’ll Need

Installing ffmpeg

Debian/Ubuntu:

sudo apt update && sudo apt install ffmpeg

macOS (Homebrew):

brew install ffmpeg

Windows (Chocolatey):

choco install ffmpeg

🛠️ Step-by-Step Setup

1. Clone the Repository

git clone https://gitlab.com/kalubaba/yt-dlp-webui
cd yt-dlp-webui

2. Create a Virtual Environment

A virtual environment keeps this app’s Python packages separate from your system.

python3 -m venv venv
source venv/bin/activate

Your terminal prompt should now show (venv) at the start.

3. Install Dependencies

pip install -r requirements.txt

This installs FastAPI, SQLAlchemy, yt-dlp, and everything else the app needs.

4. Configure Environment Variables

cp .env.example .env

Open .env in any text editor. At minimum, change the admin password:

ADMIN_PASSWORD=your-strong-password-here

See the Configuration Guide for all available settings.

5. Start the Server

./run.sh

Or manually:

uvicorn app.main:app --host 0.0.0.0 --port 8000

You should see:

Starting server on port 8000 (SSL: false)

🎉 Your First Login

1. Open http://localhost:8000 in your browser
2. Log in with:
   • Username: admin
   • Password: (whatever you set in .env, or admin123 if you didn’t change it)

⚠️ Security warning: If you’re deploying on the internet, change the default password and set APP_SECRET_KEY to a random string.

📥 Your First Download

1. Find a video URL (e.g., a YouTube video)
2. Paste it in the download box on the dashboard
3. Pick a preset:
   • General Video for the best quality
   • Audio Only to save as MP3
4. Click Download

Watch the progress bar fill up. When it reaches 100%, your file is ready in the downloads/ folder.

🔄 Development Mode (Auto-Reload)

If you’re testing or modifying the app, run in development mode:

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

The server restarts automatically whenever you change a file.

⏭️ Next Steps

Now that your server is running successfully, you can:

• Secure and customize your app using the Configuration Guide
• Learn about presets and playlist automation in the Usage Guide
• Explore the complete list of capabilities in All Features

❓ Having Trouble?

Check the Troubleshooting Guide for solutions to common issues, or the Configuration Guide for setting up HTTPS, rebranding, and more.