yt-dlp: como instalar e usar no Linux, Windows e macOS

O yt-dlp é uma ferramenta gratuita e de código aberto, executada pela linha de comando, que permite baixar áudio e vídeo de diversos sites compatíveis. É uma evolução do projeto youtube-dl e oferece recursos como seleção de formatos, download de playlists, obtenção de legendas e automação por scripts.

Neste guia você verá a instalação e o uso no Linux, Windows e macOS. Atenção: os comandos são específicos de cada sistema. Não execute comandos Linux no PowerShell nem comandos do Windows no terminal do Linux. Cada bloco identifica o ambiente correto.

O que é o yt-dlp e para que serve?

O yt-dlp identifica os formatos disponibilizados por um site e permite selecionar quais fluxos de áudio e vídeo serão baixados. Quando áudio e vídeo são entregues separadamente, ele pode usar o FFmpeg para reuni-los em um arquivo final.

Entre os recursos mais úteis estão:

• Baixar vídeos em diferentes resoluções e formatos.
• Extrair áudio e convertê-lo para formatos como MP3, FLAC e WAV.
• Baixar playlists e listas de URLs.
• Obter legendas disponíveis.
• Selecionar formatos e organizar nomes e pastas.
• Automatizar tarefas com scripts.

Requisitos e dependências

O FFmpeg deve ser o programa executável, não um pacote Python de nome parecido. Para requisitos atualizados, consulte a documentação oficial de dependências e a página de configuração do EJS.

Instalação no Linux (Debian e Ubuntu)

Os comandos desta seção são para distribuições Linux baseadas em Debian ou Ubuntu. Abra o Terminal do Linux.

Instalar dependências

# Linux: Debian e Ubuntu
sudo apt update
sudo apt install -y python3 python3-pip pipx ffmpeg

O primeiro comando atualiza a lista de pacotes. O segundo instala Python, pipx e FFmpeg.

Instalar o yt-dlp com pipx

# Linux: Debian e Ubuntu
pipx install 'yt-dlp[default]'
pipx ensurepath

O pipx mantém o aplicativo em um ambiente isolado. Depois, abra um novo terminal para que a atualização do PATH seja aplicada, se necessário.

Alternativa: instalar o executável oficial

Este método também é destinado ao Linux. Ele baixa o binário oficial para a pasta local do usuário:

# Linux: Debian e Ubuntu
mkdir -p ~/.local/bin
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

Garanta que ~/.local/bin esteja no PATH. Não use esse bloco no Windows PowerShell.

Instalação no Windows

Os comandos desta seção são para Windows 10 ou superior e devem ser executados no PowerShell.

Instalar com WinGet

# Windows: PowerShell
winget install --source winget --id yt-dlp.yt-dlp

Se o WinGet não estiver disponível, baixe o executável na página oficial do yt-dlp para Windows. Salve yt-dlp.exe em uma pasta própria e adicione essa pasta ao PATH do Windows, se quiser executar o programa de qualquer diretório.

Verificar no Windows

# Windows: PowerShell
yt-dlp --version

Instalação no macOS

Os comandos desta seção são para o Terminal do macOS, considerando que o Homebrew já esteja instalado.

# macOS: Terminal com Homebrew
brew install yt-dlp ffmpeg

Para atualizar os pacotes:

# macOS: Terminal com Homebrew
brew upgrade yt-dlp ffmpeg

Verificar a instalação e as dependências

Nos três sistemas, depois de instalar, verifique a versão do yt-dlp. Execute no terminal correspondente ao seu sistema: Linux Terminal, Windows PowerShell ou macOS Terminal.

# Linux, Windows PowerShell ou macOS
yt-dlp --version

Para conferir o FFmpeg, execute os comandos abaixo no terminal do sistema em que ele foi instalado:

# Linux, Windows PowerShell ou macOS
ffmpeg -version
ffprobe -version

Se o terminal informar que o comando não foi encontrado, instale o FFmpeg ou corrija o PATH. Para suporte completo ao YouTube, verifique também a instalação do yt-dlp-ejs e de um runtime JavaScript compatível, como Deno, conforme a documentação oficial.

Baixar um vídeo

O exemplo a seguir funciona no Linux, Windows PowerShell e macOS. Troque a URL ilustrativa pelo endereço de um conteúdo que você tenha autorização para baixar:

# Linux, Windows PowerShell ou macOS
yt-dlp "https://www.youtube.com/watch?v=ID_DO_VIDEO"

Por padrão, o yt-dlp escolhe formatos adequados entre os disponíveis. O local padrão de gravação é o diretório atual do terminal.

Consultar e escolher a qualidade

Para listar os formatos disponíveis, execute:

# Linux, Windows PowerShell ou macOS
yt-dlp -F "URL_DO_VIDEO"

A saída apresenta os identificadores de formato, resoluções, codecs e fluxos de áudio disponíveis. Os identificadores mudam de um vídeo para outro.

Para selecionar dois formatos específicos, use os identificadores mostrados na listagem. O exemplo abaixo é ilustrativo: 137 e 140 não estarão necessariamente disponíveis em todos os vídeos.

# Linux, Windows PowerShell ou macOS
yt-dlp -f 137+140 "URL_DO_VIDEO"

O sinal + solicita a combinação dos fluxos. O FFmpeg é necessário para mesclar os arquivos quando áudio e vídeo são separados.

Para priorizar a melhor combinação de vídeo e áudio disponível, com alternativa para formato combinado:

# Linux, Windows PowerShell ou macOS
yt-dlp -f "bv*+ba/b" "URL_DO_VIDEO"

Extrair áudio e converter para MP3

Para extrair somente o áudio e convertê-lo para MP3:

# Linux, Windows PowerShell ou macOS
yt-dlp -x --audio-format mp3 "URL_DO_VIDEO"

A opção -x solicita a extração do áudio e --audio-format mp3 define o formato de saída. Essa operação requer FFmpeg e ffprobe.

Outros formatos possíveis incluem FLAC, WAV e Opus:

# Linux, Windows PowerShell ou macOS
yt-dlp -x --audio-format flac "URL_DO_VIDEO"
yt-dlp -x --audio-format wav "URL_DO_VIDEO"
yt-dlp -x --audio-format opus "URL_DO_VIDEO"

Converter um arquivo para outro formato não recupera qualidade perdida na origem. Uma conversão para MP3 pode reduzir a qualidade por ser um formato com perdas.

Baixar uma playlist

Para baixar os itens de uma playlist acessível:

# Linux, Windows PowerShell ou macOS
yt-dlp "URL_DA_PLAYLIST"

Para organizar os arquivos em uma pasta com o nome da playlist e numerar os itens:

# Linux, Windows PowerShell ou macOS
yt-dlp -o "downloads/%(playlist_title)s/%(playlist_index)s - %(title)s.%(ext)s" "URL_DA_PLAYLIST"

O modelo usa o título da playlist, a posição do vídeo, o título e a extensão para formar o caminho e o nome do arquivo. O programa cria a estrutura de diretórios necessária.

Baixar legendas

Para listar os idiomas de legenda disponíveis:

# Linux, Windows PowerShell ou macOS
yt-dlp --list-subs "URL_DO_VIDEO"

Para baixar legendas fornecidas pelo publicador em português:

# Linux, Windows PowerShell ou macOS
yt-dlp --write-subs --sub-langs pt "URL_DO_VIDEO"

Para incluir legendas geradas automaticamente, quando existirem:

# Linux, Windows PowerShell ou macOS
yt-dlp --write-auto-subs --sub-langs pt "URL_DO_VIDEO"

Para tentar incorporar as legendas ao arquivo de vídeo:

# Linux, Windows PowerShell ou macOS
yt-dlp --write-subs --sub-langs pt --embed-subs "URL_DO_VIDEO"

A disponibilidade depende da plataforma, do vídeo e dos idiomas oferecidos.

Definir pasta e nome dos arquivos

Os exemplos abaixo funcionam nos três sistemas. O separador de diretórios usado no modelo de saída é tratado pelo próprio yt-dlp:

# Linux, Windows PowerShell ou macOS
yt-dlp -o "videos/%(title)s.%(ext)s" "URL_DO_VIDEO"

Para organizar por canal ou publicador:

# Linux, Windows PowerShell ou macOS
yt-dlp -o "downloads/%(uploader)s/%(title)s.%(ext)s" "URL_DO_VIDEO"

O diretório de destino precisa permitir gravação. Os campos são preenchidos com os metadados retornados pelo extrator.

Baixar vários endereços em lote

Crie um arquivo de texto chamado lista.txt com uma URL por linha:

https://www.youtube.com/watch?v=VIDEO_1
https://www.youtube.com/watch?v=VIDEO_2
https://www.youtube.com/watch?v=VIDEO_3

O arquivo é apenas uma lista de endereços, portanto pode ser criado em qualquer sistema operacional. Para processá-lo, execute:

# Linux, Windows PowerShell ou macOS
yt-dlp -a lista.txt

Para registrar os itens já baixados e evitar repetições em execuções futuras:

# Linux, Windows PowerShell ou macOS
yt-dlp --download-archive baixados.txt -a lista.txt

Atualizar o yt-dlp

O comando de atualização depende de como o programa foi instalado. Não misture os métodos.

Binário oficial no Linux ou Windows

# Linux: binário oficial
yt-dlp -U

No Windows, se a instalação foi feita pelo executável oficial e essa versão oferecer o atualizador, execute no PowerShell:

# Windows: PowerShell, executável oficial
yt-dlp -U

Instalação pelo pipx no Linux

# Linux: instalação feita com pipx
pipx upgrade yt-dlp

Instalação pelo Homebrew no macOS

# macOS: Homebrew
brew upgrade yt-dlp

Instalação pelo WinGet no Windows

# Windows: PowerShell
winget upgrade --id yt-dlp.yt-dlp

Problemas comuns e soluções

O comando yt-dlp não é encontrado

Isso normalmente significa que o diretório de instalação não está no PATH ou que o terminal ainda não foi reaberto.

# Linux: Terminal
command -v yt-dlp

# Windows: PowerShell
Get-Command yt-dlp

# macOS: Terminal
command -v yt-dlp

Confira o PATH e adicione a pasta correta às variáveis de ambiente. Depois, abra uma nova janela do terminal.

Erro relacionado ao FFmpeg

Verifique se os executáveis estão acessíveis:

# Linux, Windows PowerShell ou macOS
ffmpeg -version
ffprobe -version

Se não forem encontrados, instale o FFmpeg para seu sistema operacional e confirme se a pasta dos executáveis está no PATH.

Falha na extração do YouTube

As plataformas alteram seus mecanismos com frequência. Atualize o yt-dlp pelo método utilizado na instalação e confira as dependências EJS e o runtime JavaScript. Para diagnóstico detalhado:

# Linux, Windows PowerShell ou macOS
yt-dlp -v "URL_DO_VIDEO"

Antes de compartilhar o log, revise-o para não expor cookies, tokens ou outras informações privadas.

Formato não disponível

Os identificadores de formato variam por conteúdo. Liste novamente as opções e escolha um identificador presente no resultado:

# Linux, Windows PowerShell ou macOS
yt-dlp -F "URL_DO_VIDEO"

Conteúdo privado ou erro de autenticação

Alguns conteúdos exigem autenticação ou não estão disponíveis publicamente. Só utilize recursos de autenticação quando tiver autorização para acessar o conteúdo. Cookies e dados de sessão são credenciais: não os envie a terceiros nem os publique em logs.

Automatizar downloads no Linux com Bash

Esta seção é exclusiva para Linux e outros ambientes Unix que utilizem Bash. O script a seguir lê lista.txt, cria a pasta de destino e mantém um histórico dos itens concluídos.

#!/usr/bin/env bash
set -euo pipefail

ARQUIVO="lista.txt"
DESTINO="downloads"

if [[ ! -f "$ARQUIVO" ]]; then
    echo "Arquivo de URLs não encontrado: $ARQUIVO"
    exit 1
fi

mkdir -p "$DESTINO"

yt-dlp \
    --download-archive "$DESTINO/baixados.txt" \
    -o "$DESTINO/%(title)s.%(ext)s" \
    -a "$ARQUIVO"

echo "Processamento concluído."

Salve o conteúdo como baixar.sh. No terminal Linux, conceda permissão e execute:

# Linux: Terminal
chmod +x baixar.sh
./baixar.sh

Esse script é Bash e não deve ser executado diretamente no PowerShell. Para automatizar no Windows, crie um script próprio em PowerShell; no macOS, o Bash ou Zsh pode ser utilizado conforme o ambiente instalado.

Segurança, privacidade e direitos autorais

O fato de o yt-dlp conseguir acessar um conteúdo não significa que qualquer uso seja permitido. Respeite direitos autorais, licenças e termos aplicáveis da plataforma. Baixe conteúdos próprios, licenciados ou para os quais você tenha autorização. Não tente acessar material privado sem permissão.

Proteja cookies, tokens e credenciais. Instale o programa e suas dependências a partir de fontes confiáveis, preferencialmente os canais oficiais do projeto e dos respectivos sistemas operacionais.

Quando vale a pena utilizar o yt-dlp?

A ferramenta é útil para desenvolvedores que automatizam tarefas de mídia, pesquisadores que trabalham com materiais autorizados, equipes que organizam acervos próprios e usuários que precisam controlar formatos, legendas e processamento em lote. Para um download ocasional, uma interface gráfica pode ser mais simples; para automação e controle, a linha de comando oferece mais flexibilidade.

Conclusão

O yt-dlp oferece uma maneira flexível de baixar e processar áudio e vídeo pela linha de comando. Com a instalação correta para cada sistema operacional e o FFmpeg configurado, é possível selecionar formatos, extrair áudio, obter legendas, organizar playlists e automatizar tarefas.

Antes de executar qualquer comando, confira a identificação do sistema indicada no bloco. Mantenha a ferramenta atualizada e utilize-a respeitando as permissões e os direitos sobre o conteúdo.

Referências oficiais

• Repositório oficial do yt-dlp.
• Guia de instalação do yt-dlp.
• Dependências do yt-dlp.
• Documentação do EJS.
• Documentação do FFmpeg.
• Downloads oficiais do FFmpeg.