Como instalar o FFmpeg no Windows: um guia completo

Tim Koschützki

Cofundador · Berlim, Alemanha · Mostrar biografia

Para instalar o FFmpeg no Windows, extraia um build para Windows e adicione ao PATH a pasta que contém ffmpeg.exe. O ZIP contém uma pasta com a versão no nome, então essa pasta costuma ficar mais funda que C:\FFmpeg\bin. Este passo a passo encontra o caminho real, disponibiliza o FFmpeg para a sua conta e confirma que tudo funciona criando e inspecionando um vídeo curto.

Pré-requisitos

Use o Windows 11 em um PC x64 e o Windows PowerShell 5.1. Você precisa de conexão com a internet e de espaço para o ZIP e os arquivos extraídos. Esta instalação fica dentro do seu perfil de usuário e altera apenas o PATH do seu usuário; ela não exige um terminal de administrador.

Os comandos abaixo são para colar no PowerShell, não no Prompt de Comando. Mantenha a mesma janela do PowerShell aberta durante toda a instalação para que $bin continue disponível. Pare se algum bloco relatar um erro. Não é necessário alterar a política de execução de scripts para colar esses comandos.

Instale o build ZIP

Passo 1: baixe o FFmpeg

Abra a página oficial de download do FFmpeg⁠ e siga o link “Windows builds from gyan.dev”. O FFmpeg publica o código-fonte; o Gyan fornece os programas compilados para Windows. Na página de builds do Gyan⁠, encontre release builds e baixe ffmpeg-release-essentials.zip e o arquivo .sha256 ao lado. Salve-os na sua pasta Downloads com esses nomes, incluindo ffmpeg-release-essentials.zip.sha256. Se o navegador exibir o checksum como texto, salve a página como arquivo de texto simples com esse nome de arquivo.

Se o download do ZIP estiver lento, siga o link “mirror @ github” da página e selecione o ZIP essentials da mesma versão. Renomeie esse ZIP com a versão no nome para ffmpeg-release-essentials.zip para usar nestes comandos e use o checksum dessa mesma versão disponível na página de builds do Gyan.

O ZIP essentials inclui ffmpeg, ffprobe e o encoder libx264 usado abaixo. O ZIP funciona com o extrator integrado do PowerShell, então você não precisa do 7-Zip. O build testado é o 9.0.2-essentials_build do Gyan; o link de download pode entregar uma versão mais recente quando você acessá-lo.

O build essentials é estático. Se você escolher um build compartilhado (shared), mantenha as DLLs do FFmpeg correspondentes junto com os executáveis dele. “Full” adiciona bibliotecas externas; isso não significa que você precise dele para uma codificação H.264 comum. Atualmente o Gyan exige o Windows 10 ou posterior; este passo a passo cobre o Windows 11 x64, não versões mais antigas do Windows nem builds nativos para ARM64.

Verifique o ZIP e encontre o diretório bin

Cole este bloco no PowerShell. Se você salvou o download em outro lugar, altere $archive antes. Ele verifica o SHA-256 comparando-o com o arquivo do publicador, extrai para %LOCALAPPDATA%\Programs\FFmpeg e guarda o diretório real dos executáveis em $bin. Ele se recusa a usar um destino que já existe, inclusive um deixado por uma extração interrompida. Escolha outro destino em vez de sobrescrever uma instalação.

$bin = & {
    $ErrorActionPreference = 'Stop'
    $archive = Join-Path $env:USERPROFILE 'Downloads\ffmpeg-release-essentials.zip'
    $destination = Join-Path $env:LOCALAPPDATA 'Programs\FFmpeg'
    if (Test-Path -LiteralPath $destination) {
        throw 'The installation folder already exists. Choose a new destination.'
    }
    $expected = (Get-Content -Raw -LiteralPath "$archive.sha256").Trim()
    $actual = (Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash
    if ($expected -notmatch '^[0-9a-fA-F]{64}$' -or $actual -ne $expected) {
        throw 'SHA-256 mismatch. Download the ZIP and its checksum again.'
    }
    Expand-Archive -LiteralPath $archive -DestinationPath $destination
    $executables = @(Get-ChildItem -LiteralPath $destination -Filter ffmpeg.exe -File -Recurse)
    if ($executables.Count -ne 1) {
        throw 'Expected one ffmpeg.exe in the extracted archive.'
    }
    $executables[0].Directory.FullName
}
$bin

Para o ZIP testado, o resultado termina em Programs\FFmpeg\ffmpeg-9.0.2-essentials_build\bin. O último componente deve ser bin, e essa pasta deve conter tanto ffmpeg.exe quanto ffprobe.exe. Não adicione ao PATH o ZIP, a pasta externa da extração nem o próprio nome do arquivo executável.

O Get-FileHash⁠ compara os bytes baixados com o checksum do publicador. Uma correspondência detecta um download danificado ou incorreto; não é uma prova independente de que os arquivos do publicador são confiáveis. O Expand-Archive⁠ extrai o ZIP mantendo seus diretórios aninhados.

Adicione o FFmpeg ao PATH do seu usuário

O PATH é uma lista de diretórios em que o Windows procura comandos. O bloco a seguir acrescenta $bin ao PATH do seu usuário, preservando as entradas existentes e evitando uma duplicata idêntica. O PATH da máquina vale para todas as contas e normalmente exige permissão de administrador para ser alterado; você não precisa editá-lo para esta instalação.

& {
    $ErrorActionPreference = 'Stop'
    if (-not $bin -or -not (Test-Path -LiteralPath (Join-Path $bin 'ffmpeg.exe') -PathType Leaf)) {
        throw 'Run the extraction block successfully before changing PATH.'
    }
    $userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
    if (($userPath -split ';') -notcontains $bin) {
        $updatedPath = (@($userPath, $bin) | Where-Object { $_ }) -join ';'
        [Environment]::SetEnvironmentVariable('Path', $updatedPath, 'User')
    }
}

Isso salva o PATH da sua conta; não atualiza programas que já estão em execução. Para esta janela do PowerShell, adicione também o diretório no início do PATH do processo:

$env:Path = "$bin;$env:Path"

Um processo filho herda o ambiente do processo pai. Por isso, abrir outra aba em um terminal ou editor já aberto pode manter um PATH antigo. Feche o aplicativo de terminal inteiro e abra-o de novo pelo menu Iniciar antes de verificar se a alteração persistiu. Se ele ainda tiver o ambiente antigo, saia da sua conta do Windows e entre novamente. A documentação sobre variáveis de ambiente⁠ da Microsoft explica esses escopos de processo, usuário e máquina. A inclusão temporária no início feita acima dá preferência a esta cópia de propósito; um novo login ainda pode encontrar uma instalação mais antiga em uma posição anterior do PATH combinado.

Verificação da instalação

Verifique quais executáveis são selecionados, além das versões deles. Execute isto agora e de novo depois de reabrir o terminal:

& {
    $ErrorActionPreference = 'Stop'
    Get-Command ffmpeg, ffprobe -All | Format-List CommandType, Name, Source
    ffmpeg -version
    if ($LASTEXITCODE -ne 0) { throw 'ffmpeg could not start.' }
    ffprobe -version
    if ($LASTEXITCODE -ne 0) { throw 'ffprobe could not start.' }
}

Os dois caminhos devem apontar para dentro da pasta bin extraída, com versões de build correspondentes. Se aparecer mais de um resultado para um nome, o primeiro é o comando que o PowerShell seleciona. Um alias ou uma função também pode ter precedência sobre um executável.

Codifique um vídeo e inspecione-o

No PowerShell, vá para uma pasta onde você queira criar um pequeno vídeo de teste, como Downloads. Este exemplo gera um padrão de teste de um segundo, então não precisa de nenhum vídeo de entrada nem de GPU. Ele grava ffmpeg-check.mp4 no diretório atual. A verificação explícita do arquivo interrompe uma nova execução antes da codificação; -n também impede que o FFmpeg sobrescreva um arquivo existente. Para repetir o teste, mova esse arquivo para outro lugar ou escolha outro nome de saída na verificação e nos dois comandos.

& {
    $ErrorActionPreference = 'Stop'
    if (Test-Path -LiteralPath './ffmpeg-check.mp4') {
        throw 'Output already exists. Move it aside or choose a new filename.'
    }
    ffmpeg -hide_banner -loglevel error -nostdin -n -f lavfi -i "testsrc2=size=320x180:rate=25" -t 1 -c:v libx264 -pix_fmt yuv420p "./ffmpeg-check.mp4"
    if ($LASTEXITCODE -ne 0) { throw 'Encode failed. Check the error above before probing the output.' }
    ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height,pix_fmt:format=duration -of json "./ffmpeg-check.mp4"
    if ($LASTEXITCODE -ne 0) { throw 'ffprobe could not read the output.' }
}

O JSON deve identificar h264, largura 320, altura 180, formato de pixel yuv420p e uma duração de cerca de 1.000000 segundos. Isso verifica a codificação e a leitura de um MP4 real, indo além de apenas iniciar os programas. O FFmpeg documenta o controle de sobrescrita⁠, e os campos selecionados do ffprobe⁠ facilitam a inspeção do resultado.

Solução de problemas comuns

FFmpeg não reconhecido

Verifique se o executável funciona pelo caminho completo. Na sessão original do PowerShell, $bin ainda contém esse diretório; em uma nova sessão, defina-o com o caminho exibido durante a extração.

& {
    $ErrorActionPreference = 'Stop'
    & (Join-Path $bin 'ffmpeg.exe') -version
    if ($LASTEXITCODE -ne 0) { throw 'The selected ffmpeg.exe could not start.' }
}

Se isso funcionar, mas ffmpeg -version não, investigue a descoberta de comandos: a entrada bin correta, o PATH herdado pelo terminal e os resultados de Get-Command -All acima. Um erro “Unknown encoder” significa que o FFmpeg chegou a iniciar. Verifique se o build selecionado contém o encoder solicitado; por exemplo, execute ffmpeg -hide_banner -encoders e procure libx264.

Erros de DLL ausente

Extraia novamente o ZIP completo em uma nova pasta e confirme qual executável o PowerShell está executando. Um build compartilhado precisa das DLLs correspondentes; se você copiar apenas os arquivos .exe dele, a cópia fica sem essas DLLs. Não misture DLLs de versões diferentes nem baixe DLLs avulsas de sites não relacionados. Um build estático ainda depende de componentes do sistema Windows. Instalar o Visual C++ Redistributable mais recente não é uma solução universal para uma DLL ausente específica; siga os requisitos de runtime documentados para esse build.

Problemas de permissão

Mantenha a instalação e a saída dos testes em pastas nas quais sua conta tenha permissão de gravação. Um erro de acesso negado dentro de Program Files ou ao alterar o PATH da máquina não é motivo para executar todas as conversões como administrador. Se um PC gerenciado bloquear o download ou a execução de executáveis, use o processo aprovado de instalação de software dele.

A aceleração por hardware é uma verificação à parte

O exemplo usa codificação por CPU. Um build que lista NVENC, QSV ou outro componente de hardware não prova que seu PC consegue usá-lo: também é preciso haver hardware e drivers compatíveis. A documentação de -hwaccels⁠ do FFmpeg faz essa distinção. Faça a codificação por software funcionar antes de diagnosticar um encoder de GPU.

Se você já usa um gerenciador de pacotes

A página de builds⁠ do Gyan também lista pacotes do Chocolatey, do Scoop e do WinGet. Eles são uma alternativa a esta instalação manual; use o mesmo gerenciador para atualizações e remoção e verifique qual build o pacote dele instala. Evite manter os dois métodos no PATH, a menos que você pretenda escolher entre eles. A configuração de gerenciadores de pacotes está fora do escopo deste passo a passo.

Atualização do FFmpeg

Para esta instalação manual, baixe o novo ZIP e o checksum dele e repita o bloco de extração com um destino diferente, como Programs\FFmpeg-new. Execute os blocos do PATH usando o novo $bin e repita a verificação de codificação e inspeção com um novo nome de arquivo de saída. Mantenha a pasta anterior até que o novo build funcione.

Depois, pesquise no menu Iniciar por “Editar as variáveis de ambiente para sua conta”, edite Path em Variáveis de usuário e remova exatamente a entrada bin antiga, mantendo a nova e todas as entradas não relacionadas. Reinicie o terminal e verifique Get-Command novamente antes de excluir a instalação antiga. Para desinstalar uma cópia manual, remova a entrada dela do PATH do usuário e depois a pasta extraída.