---
title: YT DL
emoji: 🏃
colorFrom: yellow
colorTo: gray
sdk: docker
pinned: false
---
# 🎥 YouTube Cloud Downloader

A modern, cloud-ready web application to download YouTube videos (MP4) and extract audio (MP3). Built with **Python**, **Gradio**, and **yt-dlp**. 

This project is containerized using Docker, making it exceptionally easy to host on cloud platforms like **Hugging Face Spaces**.

## ✨ Features
- **High-Quality Downloads:** Leverages `yt-dlp` to pull the best available audio and video streams.
- **Format Selection:** Easily toggle between Video (MP4) or Audio (MP3).
- **Real-time Progress:** Live progress bar tracking the download and processing states.
- **Multi-User Safe:** Uses isolated UUID session folders to prevent file conflicts when multiple users use the tool simultaneously.

## 🚀 Deploying to Hugging Face Spaces

Hugging Face Spaces provides an excellent, free way to host Dockerized machine learning and utility apps.

1. Log in to Hugging Face and navigate to your profile.
2. Click **New Space**.
3. Name your space (e.g., `youtube-downloader`).
4. Under **Space SDK**, select **Docker** (choose the "Blank" Docker template).
5. Under **Space Hardware**, the free "CPU basic" tier is sufficient.
6. Create the space.
7. Once the space is created, click on **Files** and upload the following files from this repository:
   - `main.py`
   - `requirements.txt`
   - `Dockerfile`

Hugging Face will automatically detect the `Dockerfile`, install system dependencies like `ffmpeg`, install the Python requirements, and launch your Gradio UI on port 7860!

## 💻 Running Locally

If you want to run or test the application on your own machine:

### Prerequisites
- Python 3.9+
- FFmpeg installed and accessible in your system's PATH.

### Setup
1. Clone the repository or download the files.
2. (Optional) Create a virtual environment:
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
   ```
3. Install Python dependencies:
   ```bash
   pip install -r requirements.txt
   ```
4. Run the application:
   ```bash
   python main.py
   ```