Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Guias

Comandos do yt-dlp para o dia a dia

Copie comandos para vídeo, áudio, legendas, conjuntos de dados e retomada de coletas.

Nesta página

Convenios de configuração e comando

Começando com as dependências noturnas e completas atuais
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
deno --version
ffmpeg -version
python -m yt_dlp --list-impersonate-targets

As receitas de download usam Deno e --impersonate="" como a linha de base. O último requer curl-cffi e permite que ele escolha uma impressão de impressão do navegador disponível. Linux/macOS comanda usar a sintaxe Bash; para um trabalhador programado, também faça essas dependências disponíveis nesse ambiente de serviço.

Estes exemplos de terminal usam a instalação de Python yt-dlp. Use seu ambiente virtual Python, ou substituir o Python -m yt_dlp com o comando yt-dlp de modo independente. Use o Linux primeiro, com as alternativas do macOS e do Windows no guia de configuração. Instale FFmpeg/ffprobe para fusão e Deno para a resolução do desafio do YouTube. Substituir o URL de exemplo com sua fonte.

ConvençãoPor que isso importa
Cita URLs e templatesO shell interpreta personagens como &, espaços e parentesas.
Mantenha %(ext)s em filenamesOs meios selecionados e o post-processamento determinam a extensão.
Use --no-playlist para um URL de relógioUm vídeo ligado a uma lista de reprodução não deve expandir seu trabalho inesperadamente.
Verifique sua configuração salvidaExemplos podem herdar um config global. Use --ignore-config para um teste isolado.
Windows .bat: duplo padrão percentagem sinaisUse %(id)s em um arquivo de batch, mas %(id)s em arquivos de configuração interativos PowerShell e normal.

Qualidade de vídeo e MP4

Base Line: mais recente nocturno, Deno e FFmpeg, com --impersonate="". as receitas usam Bash; substituir a URL de amostra com sua fonte.

Download um vídeo com seleção padrão
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -P downloads \
  -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Selecione os fluxos disponíveis usando as definições de yt-dlp. O contêiner não é necessariamente MP4.
Lista de formatos disponíveis
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -F "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Verificar codecs e audio-only/video-only linhas. IDs de formato numérico não são políticas de saída portáteis.
Preferindo 1080p
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -S "res:1080" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Uma preferência: se não há formato em ou abaixo do alvo disponível, a classificação pode escolher um acima dele.
Aplicar um máximo de 1080p
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -f "bv*[height<=1080]+ba/b[height<=1080]" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Um filtro: falha quando nenhum formato se encaixa. retém a escolha do codec fonte.
H.264 vídeo e AAC áudio em MP4
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -f "bv[vcodec^=avc1][height<=1080]+ba[acodec^=mp4a]/b[vcodec^=avc1][acodec^=mp4a][height<=1080]" \
  --merge-output-format mp4 "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Seleção rigorosa de codec. requer formatos de correspondência e FFmpeg para fusão de corrente separada.

Avaliação de dados: MP4 + capções + metadados

Melhor vídeo + áudio, MP4, capções e metadados
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -f "bestvideo+bestaudio/best" --merge-output-format mp4 --remux-video mp4 \
  --write-info-json --write-subs --write-auto-subs --sub-langs "en" --sub-format "vtt/best" \
  --sleep-subtitles 5 --concurrent-fragments 1 -P dataset -o "%(id)s/%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
FFmpeg combina os fluxos de fonte. o MP4 mantém os codecs de fonte; verifica a compatibilidade do decoder e a cobertura de nota separadamente.

Descarregador externo: aria2c

Duas conexões, nativos DASH/HLS
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist --downloader aria2c \
  --downloader "dash,m3u8:native" --downloader-args "aria2c:-x 2 -s 2 -j 1" \
  --concurrent-fragments 1 -P downloads "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Requer o executável aria2c. Confirme primeiro o download de um vídeo. Só então aumente as conexões e reduza-as imediatamente se surgir o erro 403.

aria2 tem sua própria implementação de rede. yt-dlp a impersonização curl-cffi não configura a impressão de impressão aria2. Se apenas o download externo falhar, use --downloader nativo e compare a mesma fonte e rota de proxy.

Audio e MP3

Salve o áudio original
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -P audio \
  -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Não MP3 conversão. útil quando o seu transcrição ou tubo de reprodução aceita o codec original.
Converter para MP3 em uma taxa de bit-target
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -x \
  --audio-format mp3 --audio-quality 192K -P audio \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Usar FFmpeg. 192K controla o codificação de saída; não restaura a qualidade da fonte.
Preferir M4A sem transcoding
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f "ba[ext=m4a]" -P audio \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Faça o erro se não estiver disponível M4A formato de áudio. Adicionar /ba apenas se a sua aplicação aceitar outros contidos de fonte.
MP3 com metadados e cobertura incorporadas
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -x \
  --audio-format mp3 --embed-metadata --embed-thumbnail -P audio \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Os passos metadata/thumbnail são adicionais pós-processamento. verificar o arquivo final, não apenas o transferência.

Capítulos e subtitulos

Lista de traços disponíveis
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --list-subs "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Leia as tags de idioma oferecidas por esta fonte antes de escolher --sub-langs.
Download fornecido apenas subtitulos em inglês
python -m yt_dlp --js-runtimes deno --impersonate="" --skip-download --write-subs \
  --sub-langs "en.*" --sub-format "vtt/best" -P captions -o "%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Não cai de volta às capções automáticas e não descarga os meios de comunicação.
Também permitem capções de inglês automáticas
python -m yt_dlp --js-runtimes deno --impersonate="" --skip-download --write-subs \
  --write-auto-subs --sub-langs "en.*" --sub-format "vtt/best" -P captions \
  -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
* pode corresponder a várias variantes em inglês. isto recebe as faixas disponíveis; não executa o reconhecimento de fala.
Converter as faixas selecionadas para SRT
python -m yt_dlp --js-runtimes deno --impersonate="" --skip-download --write-subs \
  --write-auto-subs --sub-langs "en" --convert-subs srt -P captions \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Requer FFmpeg. Selecione outro código de idioma da --list-subs se necessário.
Embutido subtitulos fornecidos em MKV
python -m yt_dlp --js-runtimes deno --impersonate="" --write-subs --sub-langs "en" \
  --embed-subs --remux-video mkv -P downloads "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Baixe os meios de comunicação, solicita subtitulos em inglês e introduza a pista disponível. Verifique se essa pista existe primeiro.

Requer todas as línguas de anotação pode aumentar significativamente o número de pedidos e arquivos. Mantenha as línguas solicitadas explicitamente para o trabalho de rotina. Preserve o ID de origem e o idioma no inventário do seu conjunto de dados para que os transcritos não sejam separados dos meios que descrevem.

Metadados e Paths de saída

Imprimir metadados de um vídeo como JSON
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --dump-json "https://www.youtube.com/watch?v=jNQXAC9IVRw" > video.json
Simula a download por padrão, mas realiza extração. A redireção substitui video.json.
Escreva um metadato completo sem mídia
python -m yt_dlp --js-runtimes deno --impersonate="" --skip-download --write-info-json \
  -P metadata -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Cria um .info.json lateral. este é o operativo dados de extractor; campos de projeto antes de expõe-o publicamente.
Baixe o mini-fonte apenas
python -m yt_dlp --js-runtimes deno --impersonate="" --skip-download --write-thumbnail \
  -P thumbnails -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Salve o mini-falante disponível no seu formato fonte. --convert-thumbnails jpg adiciona um passo de conversão quando JPEG é necessário.
Imprimir o caminho de mídia final após o processamento
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --print after_move:filepath -P downloads -o "%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Ao contrário de uma etapa padrão --print, uma impressão after_move espera para um download real e sua mudança final.
Apenas os caminhos completos para um manifesto
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --print-to-file after_move:filepath completed-paths.txt -P downloads \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Adicione, então retrasas podem produzir entradas repetidas. Tratá-lo como um log de conclusão, não um inventário desduplicado.

Tempos e capítulos

Download segundos 5 através de 10
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --download-sections "*00:00:05-00:00:10" -o "clips/%(id)s-%(section_start)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Requer FFmpeg. um limite de clipe pode alinhar-se com os quadros de teclado disponíveis; verificar a saída quando o tempo exato é importante.
Re-encodando em torno de cortes solicitados
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --download-sections "*00:00:05-00:00:10" --force-keyframes-at-cuts \
  -o "clips/%(id)s-%(section_start)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Adiciona o trabalho de reencodamento para melhorar a corte nos limites solicitados. Verifique a duração resultante e audio/video alinhamento.
Dividir um vídeo em arquivos
python -m yt_dlp --split-chapters -o "chapter:%(id)s-%(section_number)03d.%(ext)s" \
  "https://www.youtube.com/watch?v=YOUR_VIDEO_ID"
Use um vídeo com metadados de capítulo. as saídas de capítulo são separadas do original completo download; espaço de disco orçamental para ambos.

Use uma política de saída ou arquivo diferente para clipes e vídeos completos. Uma entrada de arquivo de nível fonte não codifica as vezes selecionadas start/end, então um arquivo compartilhado pode suprimir um clipe posterior que você pretende criar.

Lista de jogos e URLs

Download uma lista de URL conhecida
python -m yt_dlp --no-playlist --batch-file urls.txt -P collection -o "%(id)s.%(ext)s"
Crie um arquivo UTF-8 com um URL de visualização por linha. --no-playlist aplica-se para ver URLs que incluem o contexto da lista de reprodução.
Verificar uma lista de reprodução do YouTube sem extração de vídeo completa
python -m yt_dlp --flat-playlist \
  --dump-json "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID" > playlist.jsonl
Um JSON objeto por entrada. entradas plana podem omitir detalhes de duração e formato.
Descarregue as primeiras cinco entradas da playlist
python -m yt_dlp --playlist-items 1:5 -P collection -o "%(playlist_index)03d-%(id)s.%(ext)s" \
  "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID"
Os índices da lista de reprodução são a ordem, não a identidade.Mantenha o ID do vídeo no nome do arquivo.
Limite os vídeos elegíveis por data e duração
python -m yt_dlp --dateafter 20260101 --match-filters "!is_live & duration <= 1800" \
  --batch-file urls.txt
Requer itens não vivos com duração conhecida até 30 minutos, datados em ou após janeiro 1, 2026. Filtração ainda pode exigir pedidos por vídeo.
Fica após 10 novas downloads
python -m yt_dlp --download-archive archive.txt --max-downloads 10 --batch-file urls.txt
O limite controla os arquivos recém-caixados, não quantos pedidos listing/extraction ocorrem.

Arquivos e recuperação

Resumo de uma coleção com a mesma política
python -m yt_dlp --download-archive archive.txt --continue --no-abort-on-error -P collection \
  -o "%(id)s.%(ext)s" --batch-file urls.txt
IDs completos são esquecidos. downloads parciais resumem onde suportados. use os mesmos arquivos e vias de saída como o trabalho original.
Peça um trabalhador e vincule as suas aposentadorias
python -m yt_dlp --sleep-requests 1 --sleep-interval 5 --max-sleep-interval 10 --retries 3 \
  --fragment-retries 3 --socket-timeout 30 --batch-file urls.txt
Adicione um limite de trabalhador de nível de quebra quando vários processos compartilham uma rota ou sessão.
Cap transferência de banda
python -m yt_dlp --js-runtimes deno --impersonate="" --limit-rate 2M \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Controle a taxa de transferência de mídia. não regula o número de pedidos de extração.
Reduzir a concorrência de fragmentos nativos
python -m yt_dlp --js-runtimes deno --impersonate="" --concurrent-fragments 1 \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Comece com um fragmento ao mesmo tempo quando você investiga 403s. Outros processos de trabalhadores ainda adicionam suas próprias solicitações concorrentes.

Configuração e filenames

Carregue apenas a sua coleção explícita config
python -m yt_dlp --ignore-config --config-locations yt-dlp-work.conf --batch-file urls.txt
O nome explicitamente definido config é carregado mesmo com --ignore-config. Use caminhos completos para trabalhos planejados.
Nomes com identidade estável
python -m yt_dlp --js-runtimes deno --impersonate="" -P downloads \
  -o "%(channel_id)s/%(upload_date)s-%(title).150B [%(id)s].%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
O título é truncado em 150 bytes neste modelo. IDs distinguem títulos duplicados ou mudando.
Use um diretório temporário separado
python -m yt_dlp --js-runtimes deno --impersonate="" -P "home:downloads" -P "temp:work" \
  -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
A ação final ocorre após o processamento. Assegure-se de que ambos os diretórios têm espaço suficiente; diferentes sistemas de arquivos podem exigir uma cópia.

Para coleções de longa duração, decidir se os filenames devem ser chaves de aplicação humanas ou estáveis. Os nomes e títulos de canal podem mudar. Channel/video IDs são melhores chaves para deduplicar, com campos descritivos mantidos em metadados.

Cookies e caminhos de tempo

Use o perfil do navegador que tem acesso
python -m yt_dlp --js-runtimes deno --impersonate="" \
  --cookies-from-browser "chrome:Profile 1" \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Substituir o Profile 1 com o seu perfil de navegador real. Use cookies de sessão apenas quando necessário, e mantê-los privados.
Leia um arquivo de cookie privado existente
python -m yt_dlp --js-runtimes deno --impersonate="" --cookies private/youtube-cookies.txt \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Requer o formato de arquivo de cookie da Netscape. Uma JSON exportação não é equivalente.
Use um Deno executável fora do PATH do trabalhador
python -m yt_dlp --js-runtimes "deno:/opt/deno/bin/deno" --impersonate="" \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Substituir o caminho com o Deno binário instalado para o seu trabalhador.

Diagnóstico e Verificação

Verifique uma extracção limpa
python -m yt_dlp --js-runtimes deno --impersonate="" --ignore-config --verbose --simulate \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Remove o config implícito e não salva nenhum meio. ainda faz pedidos de extração e não prova que uma transferência vai ter sucesso.
Capturar um log de diagnóstico privado
python -m yt_dlp --js-runtimes deno --impersonate="" --ignore-config --verbose --simulate \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw" > diagnostic.log 2>&1
Redacta os valores cookie/header, as credenciais do proxy e as URLs assinadas antes de compartilhar.
Verificar fluxos e duração salvos
ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height -of json "YOUR_OUTPUT_FILE"
Use o caminho final, após o processamento. ffprobe lê os cabeçalhos; não decode cada quadro.
Desconectar o arquivo salvo sem criar uma saída
ffmpeg -v error -i "YOUR_OUTPUT_FILE" -f null -
Um exame mais profundo que lê todo o arquivo. verificar o estado de saída e mensagens.
Atualize o pacote Python e verifique a sua versão
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --version