> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/yt-dlp/yt-dlp/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start guide

> Learn how to download your first video and master basic yt-dlp commands

## Your first download

Once yt-dlp is installed, downloading a video is as simple as:

```bash theme={null}
yt-dlp "https://www.youtube.com/watch?v=BaW_jenozKc"
```

yt-dlp will automatically:

* Select the best quality video and audio
* Merge them into a single file
* Save to your current directory

<Note>
  The URL should be in quotes to avoid issues with special characters in your shell.
</Note>

## Basic usage patterns

### Download best quality

By default, yt-dlp downloads the best quality available:

```bash theme={null}
yt-dlp "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

This selects the best video with the best audio and merges them using ffmpeg.

### Download audio only

To download just the audio:

```bash theme={null}
yt-dlp -x "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

The `-x` (or `--extract-audio`) option extracts audio from the video.

### Download audio in specific format

To download and convert audio to MP3:

```bash theme={null}
yt-dlp -x --audio-format mp3 "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

Supported audio formats: `mp3`, `m4a`, `flac`, `opus`, `vorbis`, `wav`

### Download with custom output name

Specify where and how to save the file:

```bash theme={null}
yt-dlp -o "~/Videos/%(title)s.%(ext)s" "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

Common template variables:

* `%(title)s` - Video title
* `%(id)s` - Video ID
* `%(ext)s` - File extension
* `%(uploader)s` - Channel name
* `%(upload_date)s` - Upload date (YYYYMMDD)

## Common use cases

<AccordionGroup>
  <Accordion title="Download a playlist" icon="list">
    Download all videos from a playlist:

    ```bash theme={null}
    yt-dlp "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"
    ```

    Download only specific items from a playlist:

    ```bash theme={null}
    # Download items 1, 2, 3, 7, and the last 5 items
    yt-dlp -I 1:3,7,-5:: "https://www.youtube.com/playlist?list=PLAYLIST_ID"
    ```

    Download playlist with numbered filenames:

    ```bash theme={null}
    yt-dlp -o "%(playlist_index)s-%(title)s.%(ext)s" "PLAYLIST_URL"
    ```
  </Accordion>

  <Accordion title="Download entire YouTube channel" icon="tv">
    Download all uploads from a channel (including shorts and livestreams):

    ```bash theme={null}
    yt-dlp "https://www.youtube.com/@channelname"
    ```

    Or using the channel URL:

    ```bash theme={null}
    yt-dlp "https://www.youtube.com/c/channelname/videos"
    ```
  </Accordion>

  <Accordion title="Download with subtitles" icon="closed-captioning">
    Download video with automatic English subtitles:

    ```bash theme={null}
    yt-dlp --write-auto-subs --sub-lang en "VIDEO_URL"
    ```

    Download and embed subtitles in the video file:

    ```bash theme={null}
    yt-dlp --write-subs --embed-subs --sub-lang en "VIDEO_URL"
    ```

    Download all available subtitles:

    ```bash theme={null}
    yt-dlp --write-subs --sub-lang all "VIDEO_URL"
    ```
  </Accordion>

  <Accordion title="Download specific quality" icon="gauge-high">
    Download 1080p video when available:

    ```bash theme={null}
    yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" "VIDEO_URL"
    ```

    Download best video up to 720p:

    ```bash theme={null}
    yt-dlp -S "res:720" "VIDEO_URL"
    ```

    List all available formats before downloading:

    ```bash theme={null}
    yt-dlp -F "VIDEO_URL"
    ```
  </Accordion>

  <Accordion title="Download from multiple sites" icon="globe">
    yt-dlp supports thousands of sites. Just use the video URL:

    <CodeGroup>
      ```bash Vimeo theme={null}
      yt-dlp "https://vimeo.com/123456789"
      ```

      ```bash Twitter/X theme={null}
      yt-dlp "https://twitter.com/user/status/1234567890"
      ```

      ```bash TikTok theme={null}
      yt-dlp "https://www.tiktok.com/@user/video/1234567890"
      ```

      ```bash Twitch theme={null}
      yt-dlp "https://www.twitch.tv/videos/1234567890"
      ```
    </CodeGroup>

    See the [list of supported sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md) for all available extractors.
  </Accordion>

  <Accordion title="Batch download from file" icon="file-lines">
    Create a text file with URLs (one per line):

    ```txt urls.txt theme={null}
    https://www.youtube.com/watch?v=dQw4w9WgXcQ
    https://www.youtube.com/watch?v=9bZkp7q19f0
    https://vimeo.com/123456789
    # Lines starting with # are comments
    ```

    Then download all URLs:

    ```bash theme={null}
    yt-dlp -a urls.txt
    ```
  </Accordion>
</AccordionGroup>

## Essential options

<Steps>
  <Step title="Format selection">
    Control video quality and format:

    <CodeGroup>
      ```bash Best quality (default) theme={null}
      yt-dlp "VIDEO_URL"
      ```

      ```bash Specific format by ID theme={null}
      yt-dlp -f 137+140 "VIDEO_URL"
      ```

      ```bash Best MP4 format theme={null}
      yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]" "VIDEO_URL"
      ```
    </CodeGroup>

    Use `-F` to list all available formats first:

    ```bash theme={null}
    yt-dlp -F "VIDEO_URL"
    ```
  </Step>

  <Step title="Output template">
    Customize the output filename and location:

    ```bash theme={null}
    yt-dlp -o "~/Downloads/%(uploader)s/%(playlist)s/%(playlist_index)s-%(title)s.%(ext)s" "VIDEO_URL"
    ```

    Common patterns:

    * `%(title)s` - Video title
    * `%(uploader)s` - Channel/uploader name
    * `%(upload_date>%Y-%m-%d)s` - Formatted date
    * `%(playlist_index)s` - Position in playlist
    * `%(id)s` - Video ID
  </Step>

  <Step title="Download archive">
    Avoid re-downloading videos you already have:

    ```bash theme={null}
    yt-dlp --download-archive downloaded.txt "PLAYLIST_URL"
    ```

    This creates/updates `downloaded.txt` with IDs of downloaded videos. On subsequent runs, videos already in the archive are skipped.
  </Step>

  <Step title="Simulate and preview">
    Preview what would be downloaded without actually downloading:

    ```bash theme={null}
    yt-dlp -s "VIDEO_URL"
    ```

    Get video info as JSON:

    ```bash theme={null}
    yt-dlp -j "VIDEO_URL"
    ```

    Print specific fields:

    ```bash theme={null}
    yt-dlp --print "%(title)s - %(uploader)s" "VIDEO_URL"
    ```
  </Step>
</Steps>

## Practical examples

### Download music album from YouTube

```bash theme={null}
yt-dlp \
  -x --audio-format mp3 \
  -o "%(playlist_title)s/%(playlist_index)s - %(title)s.%(ext)s" \
  --embed-thumbnail \
  --add-metadata \
  "PLAYLIST_URL"
```

This:

* Extracts audio only (`-x`)
* Converts to MP3 (`--audio-format mp3`)
* Organizes by playlist with numbering
* Embeds album art (`--embed-thumbnail`)
* Adds ID3 tags (`--add-metadata`)

### Download video lecture series

```bash theme={null}
yt-dlp \
  -f "bestvideo[height<=720]+bestaudio/best[height<=720]" \
  -o "%(playlist_title)s/Lecture %(playlist_index)s - %(title)s.%(ext)s" \
  --write-subs --embed-subs --sub-lang en \
  --download-archive archive.txt \
  "PLAYLIST_URL"
```

This:

* Limits quality to 720p (smaller file size)
* Numbers lectures sequentially
* Downloads and embeds English subtitles
* Tracks downloaded videos to avoid duplicates

### Download with SponsorBlock integration

```bash theme={null}
yt-dlp \
  --sponsorblock-mark all \
  --embed-chapters \
  "VIDEO_URL"
```

Or remove sponsor segments entirely:

```bash theme={null}
yt-dlp \
  --sponsorblock-remove sponsor,intro,outro \
  "VIDEO_URL"
```

### Download livestream from the start

```bash theme={null}
yt-dlp --live-from-start "LIVESTREAM_URL"
```

<Note>
  This feature is experimental and currently only supports YouTube, Twitch, and TVer.
</Note>

## Tips and tricks

<CardGroup cols={2}>
  <Card title="Rate limiting" icon="gauge">
    Limit download speed to avoid throttling:

    ```bash theme={null}
    yt-dlp -r 50K "VIDEO_URL"
    ```

    `-r 50K` limits to 50 KB/s. Use `M` for MB/s.
  </Card>

  <Card title="Geo-restriction bypass" icon="globe">
    Use a proxy for geo-restricted content:

    ```bash theme={null}
    yt-dlp --proxy socks5://127.0.0.1:1080 "VIDEO_URL"
    ```
  </Card>

  <Card title="Cookies from browser" icon="cookie">
    Download videos requiring login:

    ```bash theme={null}
    yt-dlp --cookies-from-browser chrome "VIDEO_URL"
    ```

    Supported browsers: chrome, firefox, safari, edge, opera, brave
  </Card>

  <Card title="Thumbnail embedding" icon="image">
    Embed video thumbnail as cover art:

    ```bash theme={null}
    yt-dlp --embed-thumbnail --convert-thumbnails jpg "VIDEO_URL"
    ```
  </Card>
</CardGroup>

## Getting help

View all available options:

```bash theme={null}
yt-dlp --help
```

Check version and loaded dependencies:

```bash theme={null}
yt-dlp --version
yt-dlp --verbose
```

List all supported extractors:

```bash theme={null}
yt-dlp --list-extractors
```

## Next steps

<CardGroup cols={2}>
  <Card title="Format selection" icon="filter" href="/core-concepts/format-selection">
    Learn advanced format selection and sorting
  </Card>

  <Card title="Output templates" icon="file" href="/core-concepts/output-templates">
    Master powerful output template syntax
  </Card>

  <Card title="Configuration files" icon="gear" href="/core-concepts/configuration">
    Set up default options in config files
  </Card>

  <Card title="Post-processing" icon="wand-magic-sparkles" href="/guides/post-processing">
    Convert, merge, and modify downloaded videos
  </Card>
</CardGroup>