Requisitos do Sistema

• Python 3.6 ou superior (3.8+ recomendado)
• Acesso à internet
• pip atualizado

Instalação via pip (recomendado)

A maneira mais simples de instalar o pytube3 é via pip:

Copiarpip install pytube3

Instalação com ambiente virtual

É uma boa prática usar um ambiente virtual para isolar as dependências do projeto:

Copiar# Criar ambiente virtual
python -m venv venv

# Ativar no Linux/macOS
source venv/bin/activate

# Ativar no Windows
venv\Scripts\activate

# Instalar pytube3
pip install pytube3

Instalação a partir do código-fonte

Para obter a versão mais recente diretamente do repositório GitHub:

Copiargit clone https://github.com/hgrecco/pytube3.git
cd pytube3
pip install -e .

Verificando a instalação

Copiarpython -c "import pytube; print(pytube.__version__)"

Atualização

Copiarpip install --upgrade pytube3

Seu primeiro download

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
yt.streams.first().download()

Com apenas três linhas você já tem o vídeo baixado na pasta atual! Vamos entender cada passo.

Importar e criar o objeto YouTube

Copiarfrom pytube import YouTube

# Passa a URL do vídeo como argumento
yt = YouTube("https://www.youtube.com/watch?v=SEU_VIDEO_ID")

Acessar metadados do vídeo

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

print("Título:    ", yt.title)
print("Autor:     ", yt.author)
print("Duração:   ", yt.length, "segundos")
print("Descrição: ", yt.description[:200])
print("Miniatura: ", yt.thumbnail_url)
print("Views:     ", yt.views)
print("Publicado: ", yt.publish_date)
print("Avaliação: ", yt.rating)

Listar streams disponíveis

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Exibe todos os streams disponíveis
for stream in yt.streams:
    print(stream)

A saída será algo como:

Copiar<Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2" progressive="True" type="video">
<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2" progressive="True" type="video">
<Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028" progressive="False" type="video">
...

Baixar a melhor resolução

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Stream de melhor qualidade com áudio+vídeo
stream = yt.streams.get_highest_resolution()
stream.download(output_path="/meus/videos", filename="meu_video.mp4")
print("Download concluído!")

Baixar apenas o áudio

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Stream de áudio com maior bitrate
audio = yt.streams.filter(only_audio=True).first()
audio.download(output_path=".", filename="musica.mp4")
print("Áudio baixado!")

O que são Streams?

Quando um vídeo é disponibilizado no YouTube, ele é codificado em múltiplos formatos e resoluções — cada um desses é chamado de stream. O pytube3 permite inspecionar e baixar qualquer um desses streams.

Tipos de Stream

Acessando o objeto StreamQuery

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# O atributo .streams retorna um objeto StreamQuery
streams = yt.streams
print(type(streams))  # <class 'pytube.query.StreamQuery'>

# Listar todos
for s in streams:
    print(s)

Atributos de um Stream

Métodos de download

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
stream = yt.streams.get_highest_resolution()

# Baixar para o diretório atual
stream.download()

# Especificar pasta de destino
stream.download(output_path="C:/Videos")

# Especificar nome do arquivo
stream.download(filename="rick_roll.mp4")

# Pasta + nome
stream.download(output_path="C:/Videos", filename="rick_roll.mp4")

# Obter bytes sem salvar em disco
data = stream.download(skip_existing=False)

Verificar tamanho antes de baixar

Copiarstream = yt.streams.get_highest_resolution()

# Tamanho em bytes
bytes_total = stream.filesize
mb = bytes_total / (1024 * 1024)
print(f"Tamanho: {mb:.1f} MB")

Método filter()

O método filter() aceita múltiplos parâmetros e retorna um novo StreamQuery com apenas os streams que satisfazem todos os critérios.

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Filtrar por tipo progressivo (áudio + vídeo)
streams = yt.streams.filter(progressive=True)

# Filtrar apenas vídeos
videos = yt.streams.filter(type="video")

# Filtrar apenas áudios
audios = yt.streams.filter(type="audio")

# Filtrar por extensão
mp4s = yt.streams.filter(file_extension="mp4")

# Filtrar por resolução
hd = yt.streams.filter(res="720p")

# Filtrar por codec de vídeo
h264 = yt.streams.filter(video_codec="avc1.640028")

# Combinar filtros (AND lógico)
best = yt.streams.filter(progressive=True, file_extension="mp4")

Parâmetros disponíveis para filter()

Métodos de seleção

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Primeiro resultado
primeiro = yt.streams.first()

# Último resultado
ultimo = yt.streams.last()

# Por itag específico
stream = yt.streams.get_by_itag(22)

# Maior resolução disponível (progressivo)
melhor = yt.streams.get_highest_resolution()

# Menor resolução disponível
pior = yt.streams.get_lowest_resolution()

# Melhor qualidade de áudio
audio = yt.streams.get_audio_only()

Ordenação

Copiar
# Ordenar por atributo
ordenado = yt.streams.order_by("resolution").desc()

for s in ordenado:
    print(s.resolution, s.mime_type)

Filtros personalizados com lambda

Copiar
# Apenas streams maiores que 100 MB
grandes = yt.streams.filter(
    custom_filter_functions=[
        lambda s: s.filesize > 100 * 1024 * 1024
    ]
)

# Streams progressivos em MP4 com resolução maior que 360p
from pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
bons = yt.streams.filter(
    custom_filter_functions=[
        lambda s: s.is_progressive and
                  s.mime_type == "video/mp4" and
                  int((s.resolution or "0p")[:-1]) > 360
    ]
)

Importar e usar a classe Playlist

Copiarfrom pytube import Playlist

pl = Playlist("https://www.youtube.com/playlist?list=PLxxxxxxxxxxxxxxx")

# Título da playlist
print(pl.title)

# Lista de URLs dos vídeos
for url in pl.video_urls:
    print(url)

Baixar todos os vídeos da playlist

Copiarfrom pytube import Playlist, YouTube

pl = Playlist("https://www.youtube.com/playlist?list=PLxxxxxxxxxxxxxxx")

print(f"Baixando {len(pl.video_urls)} vídeos de: {pl.title}")

for i, url in enumerate(pl.video_urls):
    yt = YouTube(url)
    stream = yt.streams.get_highest_resolution()
    stream.download(output_path="minha_playlist")
    print(f"  [{i+1}] {yt.title} ✓")

Atributos da Playlist

Baixar playlist com tratamento de erros

Copiarfrom pytube import Playlist, YouTube
from pytube.exceptions import VideoUnavailable

pl = Playlist("https://www.youtube.com/playlist?list=PLxxxxxxxxxxxxxxx")

for url in pl.video_urls:
    try:
        yt = YouTube(url)
        yt.streams.get_highest_resolution().download("playlist_output")
        print(f"✓ {yt.title}")
    except VideoUnavailable:
        print(f"✗ Vídeo indisponível: {url}")
    except Exception as e:
        print(f"✗ Erro em {url}: {e}")

Listar legendas disponíveis

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Dicionário de legendas disponíveis
print(yt.captions)
# {'en': <Caption lang="English" code="en">, 'pt': <Caption lang="Portuguese" code="pt">, ...}

Obter uma legenda específica

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Por código de idioma
legenda_pt = yt.captions.get_by_language_code("pt")
legenda_en = yt.captions.get_by_language_code("en")

if legenda_pt:
    print(legenda_pt.name)    # "Portuguese"
    print(legenda_pt.code)    # "pt"

Gerar SRT (formato de legenda padrão)

Copiarfrom pytube import YouTube

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
legenda = yt.captions.get_by_language_code("en")

# Gerar conteúdo SRT
srt_content = legenda.generate_srt_captions()
print(srt_content[:500])

# Salvar em arquivo
with open("legenda.srt", "w", encoding="utf-8") as f:
    f.write(srt_content)

Salvar XML original

Copiarlegenda = yt.captions.get_by_language_code("en")

# XML bruto do YouTube
xml_content = legenda.xml_captions
with open("legenda.xml", "w", encoding="utf-8") as f:
    f.write(xml_content)

Atributos da classe Caption

Callback de progresso

O pytube3 permite registrar callbacks que são chamados periodicamente durante o download, possibilitando a exibição de barras de progresso ou logs customizados.

Copiarfrom pytube import YouTube

def ao_progredir(stream, chunk, bytes_restantes):
    """Chamado a cada chunk baixado."""
    total = stream.filesize
    baixado = total - bytes_restantes
    porcentagem = (baixado / total) * 100
    print(f"\r⬇️  {porcentagem:.1f}%  [{baixado // 1024} KB / {total // 1024} KB]", end="")

def ao_completar(stream, caminho):
    """Chamado quando o download finaliza."""
    print(f"\n✅ Download completo: {caminho}")

yt = YouTube(
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    on_progress_callback=ao_progredir,
    on_complete_callback=ao_completar
)

yt.streams.get_highest_resolution().download()

Barra de progresso com tqdm

Copiarfrom pytube import YouTube
from tqdm import tqdm

barra = None

def init_barra(stream, *args):
    global barra
    barra = tqdm(total=stream.filesize, unit="B", unit_scale=True, desc=stream.title[:30])

def atualizar_barra(stream, chunk, bytes_restantes):
    if barra:
        barra.update(len(chunk))

def fechar_barra(stream, caminho):
    if barra:
        barra.close()

yt = YouTube(
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    on_progress_callback=atualizar_barra,
    on_complete_callback=fechar_barra
)
yt.streams.get_highest_resolution().download()

Assinaturas dos callbacks

Classe YouTube

Classe principal para interagir com um vídeo do YouTube.

Construtor

CopiarYouTube(
    url: str,
    on_progress_callback: Optional[Callable] = None,
    on_complete_callback: Optional[Callable] = None,
    proxies: Optional[Dict[str, str]] = None,
    use_oauth: bool = False,
    allow_oauth_cache: bool = True
)

Atributos da classe YouTube

Classe StreamQuery

Retornado por YouTube.streams. Suporta filtragem, ordenação e seleção de streams.

Classe Stream

Uso com proxy

Copiarfrom pytube import YouTube

proxies = {
    "http":  "http://usuario:senha@proxy.exemplo.com:8080",
    "https": "https://usuario:senha@proxy.exemplo.com:8080",
}

yt = YouTube("https://www.youtube.com/watch?v=dQw4w9WgXcQ", proxies=proxies)
yt.streams.first().download()

Hierarquia de Exceções

CopiarPytubeError
├── MaxRetriesExceeded
├── HTMLParseError
├── ExtractError
├── RegexMatchError
├── VideoUnavailable
│   ├── VideoPrivate
│   └── VideoRegionBlocked
├── AgeRestrictedError
├── LiveStreamError
├── RecordingUnavailable
├── MembersOnly
├── VideoNotFound
├── UnknownVideoError
└── PytubeURLError

Referência de todas as exceções

Exemplo de tratamento de exceções

Copiarfrom pytube import YouTube
from pytube.exceptions import (
    VideoUnavailable,
    VideoPrivate,
    VideoRegionBlocked,
    AgeRestrictedError,
    LiveStreamError,
    MembersOnly,
    MaxRetriesExceeded,
    RegexMatchError,
)

url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

try:
    yt = YouTube(url)
    yt.streams.get_highest_resolution().download()
    print("✅ Download concluído!")

except VideoPrivate:
    print("❌ Vídeo privado. Sem acesso.")
except VideoRegionBlocked:
    print("❌ Bloqueado na sua região. Tente com proxy.")
except AgeRestrictedError:
    print("❌ Restrição de idade. Use autenticação OAuth.")
except LiveStreamError:
    print("❌ Transmissão ao vivo em andamento. Tente após o término.")
except MembersOnly:
    print("❌ Conteúdo exclusivo para membros.")
except VideoUnavailable:
    print("❌ Vídeo indisponível.")
except MaxRetriesExceeded:
    print("❌ Muitas tentativas falharam. Verifique sua conexão.")
except RegexMatchError:
    print("❌ Erro de parsing. Atualize o pytube3: pip install --upgrade pytube3")
except Exception as e:
    print(f"❌ Erro inesperado: {e}")

Configuração do ambiente de desenvolvimento

Copiar# 1. Faça um fork do repositório e clone
git clone https://github.com/SEU_USUARIO/pytube3.git
cd pytube3

# 2. Crie um ambiente virtual
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# 3. Instale em modo de desenvolvimento com extras de teste
pip install -e ".[dev]"

Executando os testes

Copiar# Todos os testes
pytest

# Com cobertura de código
pytest --cov=pytube

# Apenas um arquivo de teste específico
pytest tests/test_streams.py

# Com saída verbosa
pytest -v

Padrões de código

Copiar# Verificar linting com flake8
flake8 pytube/

# Formatar com black
black pytube/

# Verificar tipos com mypy
mypy pytube/

Fluxo de contribuição (Git Flow)

Copiar# 1. Crie uma branch para sua feature
git checkout -b feature/minha-melhoria

# 2. Faça as alterações e commit seguindo Conventional Commits
git add .
git commit -m "feat: adiciona suporte a download de shorts"

# 3. Envie para o GitHub
git push origin feature/minha-melhoria

# 4. Abra um Pull Request no repositório original

Tipos de contribuição bem-vindas