yt-dlp: Guia de Instalação e Uso

1. O Que É o yt-dlp, para Que Serve e Como Funciona

1.1 O Que É

O yt-dlp é um aplicativo de linha de comando que baixa áudio e vídeo de milhares de sites [YT-DLP, s.d.c]. O projeto nasceu como fork do youtube-dl, com base no youtube-dlc, hoje inativo. A comunidade mantém o código no repositório github.com/yt-dlp/yt-dlp sob a licença Unlicense. O programa é escrito em Python, e os binários oficiais já trazem o interpretador embutido [YT-DLP, s.d.c]. O repositório publica a lista de sites suportados [YT-DLP, s.d.b].

1.2 Para Que Serve

O yt-dlp atende a 8 tarefas principais:

1. baixar vídeo e áudio de um endereço;

2. listar os formatos disponíveis de um vídeo e escolher um deles;

3. extrair o áudio e converter para mp3, m4a, flac e outros formatos;

4. baixar legendas de autor e legendas geradas automaticamente;

5. baixar playlists inteiras ou itens escolhidos por posição;

6. baixar um trecho de um vídeo;

7. gravar metadados e capa no arquivo final;

8. repetir downloads por lista de endereços e arquivo de configuração.

1.3 Como Funciona

O yt-dlp executa uma sequência de sete etapas a cada endereço recebido. O registro de uma execução real confirma cada etapa: a linha Downloading webpage marca a leitura da página, a linha [jsc:deno] marca a resolução do desafio JavaScript, a linha Downloading 1 format(s) marca a seleção de formato, e a linha [Merger] marca a mesclagem.

Figura 1. Sequência de Etapas de um Download no yt-dlp

O arquivo final fica na pasta atual do PowerShell. As opções -P e -o definem outro destino e outro nome [YT-DLP, s.d.c].

2. O Que É Linha de Comando

2.1 Definição e Componentes

A linha de comando é uma interface de texto. O usuário digita uma instrução, aperta a tecla Enter, o sistema executa a instrução e devolve o resultado em texto. A interface gráfica opera com janelas, botões e mouse. A linha de comando opera com teclado e instruções escritas, e permite repetir a mesma tarefa com um único comando.

Quadro 1. Componentes da Linha de Comando

2.2 Anatomia de um Comando

A sintaxe do yt-dlp segue o modelo yt-dlp [OPTIONS] [--] URL [URL...] [YT-DLP, s.d.c]. Um comando completo reúne o nome do programa, as opções e o endereço:

yt-dlp -x --audio-format mp3 "https://exemplo.com/video"

Quadro 2. Partes de um Comando do yt-dlp

2.3 Regras Práticas no PowerShell

1. A tecla Enter executa o comando digitado.

2. As aspas duplas protegem a URL, porque o PowerShell interpreta o símbolo & como operador.

3. O comando cd muda a pasta atual, como em cd $env:USERPROFILE\Downloads.

4. A seta para cima recupera o comando anterior, e a tecla Tab completa nomes de pastas e arquivos.

5. Caminhos com espaço pedem aspas duplas.

6. A combinação Ctrl+C interrompe um comando em execução.

7. O comando yt-dlp --help lista todas as opções do programa [YT-DLP, s.d.c].

3. Parte A: Instalação

3.1 Componentes

Quadro 3. Componentes do Ambiente do yt-dlp

O yt-dlp exige o binário do ffmpeg. O pacote Python de mesmo nome pertence a outro projeto [YT-DLP, s.d.c].

3.2 Windows com winget

1. Instalar o yt-dlp. A busca por nome simples pode retornar duas correspondências: o pacote yt-dlp.yt-dlp da origem winget e um aplicativo de terceiros da origem msstore. O ID e a origem eliminam a ambiguidade:

   winget install --id yt-dlp.yt-dlp --exact --source winget

2. Reabrir o PowerShell. O PATH da sessão atualiza em nova janela.

3. Verificar a versão.

   yt-dlp --version

4. Instalar o Deno. O yt-dlp exige a versão 2.3.0 ou superior e ativa o Deno por padrão [YT-DLP, 2026a]:

   winget install DenoLand.Deno
   deno --version

5. Confirmar o ffmpeg:

   ffmpeg -version

   Quando o ffmpeg fica fora do PATH, a opção --ffmpeg-location informa o caminho do binário ou da pasta que o contém [YT-DLP, s.d.c].

3.3 Binário Oficial

O binário oficial dispensa a instalação separada do Python e traz o yt-dlp-ejs embutido [YT-DLP, s.d.c].

Quadro 4. Binários Oficiais por Sistema

A página de releases lista as variantes para ARM64, x86 de 32 bits, musl e as versões compactadas. A pasta que recebe o arquivo precisa estar no PATH. Em macOS, Linux e BSD, a instalação em ~/.local/bin segue a wiki do projeto [YT-DLP, 2026b]:

curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o ~/.local/bin/yt-dlp
chmod a+rx ~/.local/bin/yt-dlp

3.4 pip

python3 -m pip install -U "yt-dlp[default]"

O grupo default inclui o yt-dlp-ejs. Alguns sistemas pedem py ou python no lugar de python3. A versão nightly instala-se com --pre [YT-DLP, 2026b]:

python3 -m pip install -U --pre "yt-dlp[default]"

3.5 Gerenciadores de Pacote

Terceiros mantêm os pacotes, o que pode gerar atraso em relação ao lançamento oficial [YT-DLP, 2026b].

Quadro 5. Instalação por Gerenciador de Pacote

3.6 Runtime JavaScript e yt-dlp-ejs

Segundo a página EJS da wiki, o download do YouTube exige que um runtime JavaScript externo resolva desafios propostos pelo site [YT-DLP, 2026a].

Quadro 6. Runtimes JavaScript Aceitos

O yt-dlp-ejs segue regras próprias por forma de instalação:

1. Binários oficiais: o componente vem embutido.

2. pip ou pipx: yt-dlp[default] instala o componente. As alternativas são --remote-components ejs:npm [Deno e Bun] e --remote-components ejs:github.

3. Pacotes de terceiros: a necessidade depende de o repositório empacotar o componente. Na ausência, as mesmas opções --remote-components suprem a lacuna.

A wiki recomenda gravar as opções --remote-components no arquivo de configuração [seção 4.11] [YT-DLP, 2026a].

3.7 Verificação da Instalação

yt-dlp --version
deno --version
ffmpeg -version

A execução com -v imprime, no início da saída, as dependências que o yt-dlp reconhece na máquina [YT-DLP, s.d.c].

3.8 Atualização

Quadro 7. Comandos de Atualização

O README descreve três canais de atualização para os binários: stable [padrão], nightly e master. O README recomenda o nightly a usuários regulares, porque o stable costuma ficar defasado diante de mudanças dos sites [YT-DLP, s.d.c]. A troca de canal usa:

yt-dlp --update-to nightly

Versões com mais de 90 dias geram um aviso de atualização, que a opção --no-update suprime [YT-DLP, s.d.c].

4. Parte B: Uso

4.1 Sintaxe Geral

yt-dlp [OPTIONS] [--] URL [URL...]

O PowerShell trata o símbolo & como operador. A URL entre aspas duplas preserva o endereço inteiro.

4.2 Primeiro Download

cd $env:USERPROFILE\Downloads
yt-dlp "https://www.youtube.com/watch?v=ID_DO_VIDEO"

A saída de uma execução real mostra a sequência de etapas:

1. Extração: o yt-dlp identifica o site e baixa a página e os dados do player.

2. Desafio JavaScript: a linha [jsc:deno] Solving JS challenges using deno indica a resolução pelo Deno.

3. Seleção de formato: a linha Downloading 1 format(s): 135+251 indica um formato de vídeo [135] e um de áudio [251].

4. Download: o yt-dlp grava um arquivo para cada formato.

5. Mesclagem: a etapa [Merger] une os dois arquivos em um .mkv.

6. Limpeza: o yt-dlp apaga os arquivos originais. A opção -k os mantém.

4.3 Vídeo ou Playlist

Uma URL que contém vídeo e playlist gera, por padrão, o download da playlist. As opções definem o comportamento:

yt-dlp --no-playlist "URL"
yt-dlp --yes-playlist "URL"
yt-dlp -I 1:3,7 "URL_DA_PLAYLIST"

A opção -I seleciona itens por posição, aceita intervalos no formato INÍCIO:FIM:PASSO e aceita índices negativos para contar a partir do fim [YT-DLP, s.d.c].

4.4 Pasta e Nome do Arquivo

yt-dlp -P "C:\Users\SEU_USUARIO\Downloads\Videos" -o "%(title)s [%(id)s].%(ext)s" "URL"

A opção -P define a pasta, e -o define o template de saída. Os campos mais usados são title, id, ext, uploader, channel e upload_date. A opção --print after_move:filepath imprime o nome final do arquivo, depois da mesclagem e da movimentação [YT-DLP, s.d.c].

4.5 Listar e Escolher Formatos

yt-dlp -F "URL"
yt-dlp -f CODIGO "URL"

A opção -F lista os formatos disponíveis sem baixar o vídeo. A opção -f recebe o código do formato. A opção -S ordena os formatos por campos como resolução e codec [YT-DLP, s.d.c].

4.6 Extração de Áudio

yt-dlp -x --audio-format mp3 --audio-quality 0 "URL"

A opção -x converte o vídeo em um arquivo de áudio e exige ffmpeg e ffprobe. O parâmetro --audio-format aceita best [padrão], aac, alac, flac, m4a, mp3, opus, vorbis e wav. O parâmetro --audio-quality aceita valores de 0 [melhor] a 10 [pior] para taxa variável, ou uma taxa fixa como 128K [YT-DLP, s.d.c].

4.7 Contêiner de Saída e Presets

yt-dlp --merge-output-format mp4 "URL"

O parâmetro --merge-output-format aceita avi, flv, mkv, mov, mp4 e webm. A mesma lógica vale para o remux [troca de contêiner] por --remux-video. A opção -t aplica conjuntos prontos de opções [YT-DLP, s.d.c]:

Quadro 8. Presets do yt-dlp

4.8 Metadados e Capa

yt-dlp --embed-metadata --embed-thumbnail "URL"

A opção --embed-metadata grava título e dados correlatos no arquivo, e --embed-thumbnail grava a miniatura como capa. Alguns formatos usam as bibliotecas mutagen ou AtomicParsley para a capa [YT-DLP, s.d.c].

4.9 Legendas

yt-dlp --list-subs "URL"
yt-dlp --write-subs --write-auto-subs --sub-langs "pt.*" --skip-download "URL"

A opção --list-subs lista as legendas disponíveis. A opção --write-subs grava legendas enviadas pelo autor, e --write-auto-subs grava as geradas automaticamente. O parâmetro --sub-langs aceita expressões regulares, como "en.*,ja", e a palavra all. A opção --skip-download grava as legendas sem baixar o vídeo. A opção --convert-subs converte para ass, lrc, srt ou vtt [YT-DLP, s.d.c].

4.10 Trechos, Lotes e Registro de Downloads

Trecho de vídeo [exige ffmpeg]:

yt-dlp --download-sections "*10:15-inf" "URL"

O prefixo * indica intervalo de tempo, e a palavra inf indica o fim do vídeo.

Lista de URLs em arquivo de texto, com uma URL por linha:

yt-dlp -a lista.txt

Registro de downloads concluídos, que evita repetição em execuções futuras [YT-DLP, s.d.c]:

yt-dlp --download-archive registro.txt "URL_DA_PLAYLIST"

4.11 Cookies e Arquivo de Configuração

Cookies do navegador, para conteúdo que exige sessão autenticada:

yt-dlp --cookies-from-browser firefox "URL"

O parâmetro aceita brave, chrome, chromium, edge, firefox, opera, safari, vivaldi e whale [YT-DLP, s.d.c].

Arquivo de configuração. No Windows, o local recomendado é %APPDATA%\yt-dlp\config. O arquivo yt-dlp.conf na pasta do binário também é válido. Cada linha recebe uma opção, sem espaço depois dos hífens, e linhas iniciadas por # são comentários [YT-DLP, s.d.c]:

# Pasta e nome padrão
-P ~/Downloads
-o "%(title)s [%(id)s].%(ext)s"

# Contêiner e playlist
--merge-output-format mp4
--no-playlist

A opção --ignore-config desativa a leitura de arquivos em uma execução específica.

4.12 Diagnóstico

Quadro 9. Opções de Diagnóstico

Uma falha em site recente pede a atualização ao canal nightly antes de qualquer relato de erro, conforme o README [YT-DLP, s.d.c].

4.13 Uso Responsável

A licença Unlicense rege o código do yt-dlp. O conteúdo baixado segue os direitos autorais do titular e os termos de uso da plataforma de origem. O uso do programa depende da verificação, pelo usuário, da licitude de cada download.

5. Em Linguagem Simples

O yt-dlp funciona como um assistente que recebe um endereço de vídeo, visita o site, escolhe um arquivo de imagem e um arquivo de som, baixa os dois e junta tudo em um único arquivo. O usuário conversa com o assistente por texto, na janela do PowerShell.

A instalação reúne três programas: o yt-dlp, que baixa; o Deno, que resolve os testes do YouTube; e o ffmpeg, que junta imagem e som. O comando winget install instala os dois primeiros, e a máquina testada já continha o terceiro.

O uso resume-se a uma frase: digitar yt-dlp, um espaço e o endereço entre aspas. As opções, como -x para áudio, ajustam o resultado.

6. FAQ

6.1 O yt-dlp Tem Interface Gráfica?

O projeto oficial opera por linha de comando. A wiki indica interfaces gráficas de terceiros para quem prefere janelas [YT-DLP, 2026b].

6.2 Por Que o YouTube Exige o Deno?

O YouTube impõe desafios em JavaScript. O Deno executa os scripts do yt-dlp-ejs que resolvem os desafios, e o yt-dlp ativa o Deno por padrão [YT-DLP, 2026a].

6.3 Qual a Diferença Entre o yt-dlp e o youtube-dl?

O yt-dlp deriva do youtube-dl e adota comportamentos próprios, descritos na seção “Changes from youtube-dl” do README [YT-DLP, s.d.c].

6.4 Por Que o Arquivo Saiu em .mkv?

O yt-dlp escolhe o contêiner na mesclagem. A opção --merge-output-format mp4 define o mp4 quando o usuário prefere o mp4 [YT-DLP, s.d.c].

6.5 Onde Ficam os Arquivos Baixados?

Os arquivos ficam na pasta atual do PowerShell. As opções -P e -o definem outro destino [YT-DLP, s.d.c].

6.6 Como Baixar Apenas o Áudio?

A opção -x extrai o áudio, e --audio-format escolhe o formato, como em yt-dlp -x --audio-format mp3 "URL".

6.7 O Que Fazer Quando um Site Muda e o Download Falha?

A atualização resolve a maioria dos casos. O README recomenda o canal nightly e a execução com -v para registrar o erro [YT-DLP, s.d.c].

6.8 A Licença Autoriza o Download de Qualquer Conteúdo?

A Unlicense rege o código do programa. Os direitos autorais e os termos de uso da plataforma regem o conteúdo baixado.

7. Conclusão

O yt-dlp reúne, em um programa de linha de comando, a leitura do site, a escolha de formato, o download e o pós-processamento. A instalação no Windows exige três componentes: o yt-dlp, o Deno e o ffmpeg. O uso começa com um comando de uma linha e cresce com opções documentadas, configuráveis em arquivo. A atualização frequente mantém o programa alinhado às mudanças dos sites.

8. Glossário de Termos

Argumento

Valor posicional informado ao programa depois do nome e das opções, como a URL do vídeo.

Binário

Arquivo executável compilado, composto por instruções de máquina de uma arquitetura de processador.

Canal de Atualização

Linha de publicação de versões de um programa, identificada por nome [stable, nightly, master].

Contêiner

Formato de arquivo que reúne trilhas de vídeo, áudio e legendas em um único arquivo [mkv, mp4, webm].

Cookie

Registro de texto que o navegador grava no computador por site visitado.

Deno

Ambiente de execução de JavaScript e TypeScript distribuído como um executável único.

Desafio JavaScript

Etapa de verificação proposta pelo YouTube que exige a execução de código JavaScript.

EJS

Pacote de scripts JavaScript mantido no repositório yt-dlp/ejs, com versão compatível fixada pelo arquivo pyproject.toml do yt-dlp.

Extrator

Componente do yt-dlp associado a um site ou serviço de vídeo, identificado por nome listável com --list-extractors.

ffmpeg

Programa de linha de comando para processamento de áudio e vídeo.

ffprobe

Programa de linha de comando da família ffmpeg que lê propriedades de arquivos de mídia.

Fork

Derivação de um projeto de software mantida em repositório próprio; o yt-dlp é fork do youtube-dl.

Formato

Variante de mídia de um vídeo, identificada por código [135, 251] e definida por contêiner, codec e resolução ou taxa de bits.

Interface Gráfica

Interface formada por janelas, botões e ponteiro do mouse.

Linha de Comando

Interface de texto em que o usuário digita o nome de um programa seguido de opções.

Mesclagem

Junção de um arquivo de vídeo e um arquivo de áudio em um único arquivo.

Metadados

Dados descritivos gravados no arquivo de mídia, como título, capítulos e capa.

Nightly

Canal de atualização do yt-dlp que publica versões pouco antes da meia-noite UTC nos dias com alteração de código.

Opção

Parâmetro nomeado de um comando, iniciado por um hífen [forma curta] ou por dois hífens [forma longa].

PATH

Variável de ambiente que reúne a lista de pastas pesquisadas pelo sistema operacional na busca de executáveis.

pip

Gerenciador de pacotes da linguagem Python.

Playlist

Lista ordenada de vídeos reunida sob um endereço.

Pós-processamento

Etapa posterior ao download que altera o arquivo obtido, como mesclagem, conversão e incorporação de metadados.

PowerShell

Interpretador de linha de comando e linguagem de script da Microsoft.

Prompt

Texto exibido pelo interpretador antes do cursor, com a indicação da pasta atual.

Remux

Troca do contêiner de um arquivo de mídia sem recodificação.

Runtime JavaScript

Ambiente de execução que interpreta código JavaScript fora do navegador [Deno, Node, QuickJS, Bun].

Shell

Programa interpretador de comandos digitados em um terminal.

Template de Saída

Cadeia de texto com campos no formato %(campo)s que define o nome do arquivo gravado.

Terminal

Janela de texto que recebe a digitação do usuário e exibe a saída dos programas.

Unlicense

Licença de software que dedica a obra ao domínio público.

URL

Endereço de um recurso na internet.

winget

Gerenciador de pacotes de linha de comando do Windows.

yt-dlp

Aplicativo de linha de comando para baixar áudio e vídeo, mantido em github.com/yt-dlp/yt-dlp.

zipimport

Formato de executável Python multiplataforma, empacotado em arquivo zip, que exige um interpretador Python instalado.

9. Referências Bibliográficas

DENO. Installation. In: Deno Docs. [S. l.]: Deno, 2026. Disponível em: https://docs.deno.com/runtime/getting_started/installation/. Acesso em: 28 out. 2026.

FFMPEG. FFmpeg. [S. l.]: FFmpeg, [s.d.]. Disponível em: https://www.ffmpeg.org. Acesso em: 28 out. 2026.

YT-DLP. EJS. In: yt-dlp Wiki. [S. l.]: GitHub, 2026a. Disponível em: https://github.com/yt-dlp/yt-dlp/wiki/EJS. Acesso em: 28 out. 2026.

YT-DLP. FFmpeg-Builds. [S. l.]: GitHub, [s.d.a]. Disponível em: https://github.com/yt-dlp/FFmpeg-Builds. Acesso em: 28 out. 2026.

YT-DLP. Installation. In: yt-dlp Wiki. [S. l.]: GitHub, 2026b. Disponível em: https://github.com/yt-dlp/yt-dlp/wiki/Installation. Acesso em: 28 out. 2026.

YT-DLP. Supported Sites. [S. l.]: GitHub, [s.d.b]. Disponível em: https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md. Acesso em: 28 out. 2026.

YT-DLP. yt-dlp: a feature-rich command-line audio/video downloader. [S. l.]: GitHub, [s.d.c]. Disponível em: https://github.com/yt-dlp/yt-dlp. Acesso em: 28 out. 2026.