# ytdl-org/youtube-dl architecture

> Architecture diagram of the GitHub repository ytdl-org/youtube-dl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ytdl-org/youtube-dl
- Repository: https://github.com/ytdl-org/youtube-dl

## Overview

youtube-dl is a command-line and embeddable downloader that turns supplied URLs or search terms into selected media files. Its principal workflow is: accept options and targets, match a site extractor, resolve media metadata and formats (including playlist/search results), select formats, download media, then optionally postprocess it. The README also documents proxy and geo-bypass controls, flat playlists, subtitles, and extractor listing. The graph reflects these documented capabilities; sampled excerpts are partial, so some internal dispatch details are represented only at the documented subsystem level.

Main entry points: [`youtube_dl/YoutubeDL.py`](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/YoutubeDL.py) (Download coordinator), [`youtube_dl/downloader`](https://github.com/ytdl-org/youtube-dl/tree/master/youtube_dl/downloader) (Protocol downloaders), [`youtube_dl/extractor`](https://github.com/ytdl-org/youtube-dl/tree/master/youtube_dl/extractor) (Site extractors), [`youtube_dl/downloader/__init__.py`](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/downloader/__init__.py) (Downloader dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI entry<br/>[__main__.py]"]
  node_api["Python API<br/>[__init__.py]"]
  node_core["Download coordinator<br/>[YoutubeDL.py]"]
end

subgraph group_extract["Extraction"]
  node_registry["Extractor registry<br/>[__init__.py]"]
  node_extractors["Site extractors"]
  node_shared_ie["Extractor base<br/>[common.py]"]
  node_search["Search extractor<br/>[googlesearch.py]"]
  node_formats["Format selection<br/>[YoutubeDL.py]"]
end

subgraph group_transfer["Download"]
  node_downloader_dispatch["Downloader dispatch<br/>[__init__.py]"]
  node_protocol_downloaders["Protocol downloaders"]
  node_fragment["Fragment downloader<br/>[fragment.py]"]
  node_external_dl["External downloaders<br/>[external.py]"]
end

subgraph group_finish["Output processing"]
  node_postprocess["Postprocessor dispatch<br/>[YoutubeDL.py]"]
  node_ffmpeg["FFmpeg processing<br/>[ffmpeg.py]"]
  node_thumbnail["Thumbnail embedding<br/>[embedthumbnail.py]"]
end

subgraph group_support["Runtime support"]
  node_cache["Download cache<br/>[cache.py]"]
end

node_user(("CLI user"))
node_platforms(("Video platforms"))
node_media_files["Media files"]
node_network(("Network services"))

node_user -->|"provides targets"| node_cli
node_cli -->|"invokes"| node_core
node_user -.->|"calls"| node_api
node_api -->|"creates"| node_core
node_core -->|"loads extractors"| node_registry
node_registry -->|"registers"| node_extractors
node_extractors -->|"inherits"| node_shared_ie
node_core -->|"dispatches search"| node_search
node_search -->|"requests results"| node_network
node_extractors -->|"extracts media info"| node_platforms
node_extractors -->|"returns metadata"| node_core
node_core -->|"selects formats"| node_formats
node_core -->|"requests download"| node_downloader_dispatch
node_downloader_dispatch -->|"dispatches download"| node_protocol_downloaders
node_protocol_downloaders -->|"fetches media"| node_network
node_protocol_downloaders -->|"writes media"| node_media_files
node_protocol_downloaders -.->|"uses for fragments"| node_fragment
node_fragment -->|"downloads fragments"| node_protocol_downloaders
node_downloader_dispatch -.->|"dispatches optionally"| node_external_dl
node_external_dl -.->|"fetches media"| node_network
node_core -->|"runs processors"| node_postprocess
node_postprocess -.->|"invokes when configured"| node_ffmpeg
node_postprocess -.->|"invokes when configured"| node_thumbnail
node_ffmpeg -->|"transforms files"| node_media_files
node_thumbnail -->|"embeds thumbnail"| node_media_files
node_core -.->|"uses cache"| node_cache

click node_cli "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/__main__.py"
click node_api "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/__init__.py"
click node_core "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/YoutubeDL.py"
click node_registry "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/extractor/__init__.py"
click node_extractors "https://github.com/ytdl-org/youtube-dl/tree/master/youtube_dl/extractor"
click node_shared_ie "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/extractor/common.py"
click node_search "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/extractor/googlesearch.py"
click node_formats "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/YoutubeDL.py"
click node_downloader_dispatch "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/downloader/__init__.py"
click node_protocol_downloaders "https://github.com/ytdl-org/youtube-dl/tree/master/youtube_dl/downloader"
click node_fragment "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/downloader/fragment.py"
click node_external_dl "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/downloader/external.py"
click node_postprocess "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/YoutubeDL.py"
click node_ffmpeg "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/postprocessor/ffmpeg.py"
click node_thumbnail "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/postprocessor/embedthumbnail.py"
click node_cache "https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/cache.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_api,node_core,node_user toneBlue
class node_registry,node_extractors,node_shared_ie,node_search,node_formats toneAmber
class node_downloader_dispatch,node_protocol_downloaders,node_fragment,node_external_dl toneMint
class node_postprocess,node_ffmpeg,node_thumbnail toneRose
class node_cache,node_platforms,node_media_files,node_network toneIndigo
```

## Components

### User entry

- [CLI entry](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/__main__.py): `youtube_dl/__main__.py`
- [Python API](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/__init__.py): `youtube_dl/__init__.py`
- [Download coordinator](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/YoutubeDL.py): `youtube_dl/YoutubeDL.py`

### Extraction

- [Extractor registry](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/extractor/__init__.py): `youtube_dl/extractor/__init__.py`
- [Site extractors](https://github.com/ytdl-org/youtube-dl/tree/master/youtube_dl/extractor): `youtube_dl/extractor`
- [Extractor base](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/extractor/common.py): `youtube_dl/extractor/common.py`
- [Search extractor](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/extractor/googlesearch.py): `youtube_dl/extractor/googlesearch.py`
- [Format selection](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/YoutubeDL.py): `youtube_dl/YoutubeDL.py`

### Download

- [Downloader dispatch](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/downloader/__init__.py): `youtube_dl/downloader/__init__.py`
- [Protocol downloaders](https://github.com/ytdl-org/youtube-dl/tree/master/youtube_dl/downloader): `youtube_dl/downloader`
- [Fragment downloader](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/downloader/fragment.py): `youtube_dl/downloader/fragment.py`
- [External downloaders](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/downloader/external.py): `youtube_dl/downloader/external.py`

### Output processing

- [Postprocessor dispatch](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/YoutubeDL.py): `youtube_dl/YoutubeDL.py`
- [FFmpeg processing](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/postprocessor/ffmpeg.py): `youtube_dl/postprocessor/ffmpeg.py`
- [Thumbnail embedding](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/postprocessor/embedthumbnail.py): `youtube_dl/postprocessor/embedthumbnail.py`

### Runtime support

- [Download cache](https://github.com/ytdl-org/youtube-dl/blob/master/youtube_dl/cache.py): `youtube_dl/cache.py`

### Other components

- **CLI user**
- **Video platforms**
- **Media files**
- **Network services**

## Connections

- CLI user → CLI entry: provides targets
- CLI entry → Download coordinator: invokes
- CLI user → Python API: calls
- Python API → Download coordinator: creates
- Download coordinator → Extractor registry: loads extractors
- Extractor registry → Site extractors: registers
- Site extractors → Extractor base: inherits
- Download coordinator → Search extractor: dispatches search
- Search extractor → Network services: requests results
- Site extractors → Video platforms: extracts media info
- Site extractors → Download coordinator: returns metadata
- Download coordinator → Format selection: selects formats
- Download coordinator → Downloader dispatch: requests download
- Downloader dispatch → Protocol downloaders: dispatches download
- Protocol downloaders → Network services: fetches media
- Protocol downloaders → Media files: writes media
- Protocol downloaders → Fragment downloader: uses for fragments
- Fragment downloader → Protocol downloaders: downloads fragments
- Downloader dispatch → External downloaders: dispatches optionally
- External downloaders → Network services: fetches media
- Download coordinator → Postprocessor dispatch: runs processors
- Postprocessor dispatch → FFmpeg processing: invokes when configured
- Postprocessor dispatch → Thumbnail embedding: invokes when configured
- FFmpeg processing → Media files: transforms files
- Thumbnail embedding → Media files: embeds thumbnail
- Download coordinator → Download cache: uses cache
