Save 10%Pay yearly on any plan. 6% half-yearly, 3% quarterly. Help centreWhatsAppTelegram TeamsOpen a ticket

Installing and Using FFmpeg in Python

Install FFmpeg and the ffmpeg-python package, then convert, resize, watermark and probe video from Python, with working error handling and a subprocess option.

3 min readBy Swati

Reviewed by the AmazingRDP technical team

Using FFmpeg in Python

Encoding eats CPU for hours. Run it on an Encoding RDP and keep your own computer free. See Encoding RDP from $12.99

FFmpeg is the standard command-line tool for converting and processing video and audio. Python does not include it: you install the FFmpeg program first, then a small Python package that builds and runs FFmpeg commands for you. This guide does both and then walks through the tasks people need most.

1. Install FFmpeg

Windows 10 and 11:

winget install Gyan.FFmpeg

Or download a build from the links on ffmpeg.org, unzip it, and add its bin folder to the PATH. Open a new terminal afterwards.

macOS (Homebrew):

brew install ffmpeg

Ubuntu and Debian:

sudo apt update
sudo apt install ffmpeg

Fedora:

sudo dnf install ffmpeg-free

Fedora's own package leaves out some patented codecs. The full build comes from the RPM Fusion repository.

Check that it works:

ffmpeg -version

2. Install the Python package

pip install ffmpeg-python

The name matters. The package is ffmpeg-python, although you import it as ffmpeg. Packages called ffmpeg or python-ffmpeg are different projects, and installing them by mistake causes the error module 'ffmpeg' has no attribute 'input'. If you see that, run pip uninstall ffmpeg python-ffmpeg and install ffmpeg-python again.

3. Convert a video

import ffmpeg
ffmpeg.input('input.mp4').output('output.mkv').run()

FFmpeg picks the format from the file ending. To replace an existing output file without being asked, add .overwrite_output() before .run().

4. Extract the audio

import ffmpeg
ffmpeg.input('input.mp4').audio.output('audio.mp3').run()

5. Resize a video and keep its sound

A filter applies to one stream. If you filter the whole input, the result has no sound, so take the video and audio streams separately:

import ffmpeg
src = ffmpeg.input('input.mp4')
video = src.video.filter('scale', 1280, -2)
ffmpeg.output(video, src.audio, 'output_720p.mp4').run()

-2 tells FFmpeg to work out the height from the width and keep it an even number, which most codecs need.

6. Add a watermark

import ffmpeg
src = ffmpeg.input('input.mp4')
logo = ffmpeg.input('watermark.png')
video = ffmpeg.overlay(src.video, logo, x='main_w-overlay_w-10', y='main_h-overlay_h-10')
ffmpeg.output(video, src.audio, 'output_watermark.mp4').run()

This puts the image 10 pixels from the bottom right corner.

7. Read a file's details

import ffmpeg
info = ffmpeg.probe('input.mp4')
print(info['format']['duration'])
for s in info['streams']:
    print(s['codec_type'], s['codec_name'])

probe runs ffprobe, which is installed together with FFmpeg.

8. Handle errors

FFmpeg writes its messages to the error stream. You only get them in Python if you ask run to capture them:

import ffmpeg
try:
    ffmpeg.input('input.mp4').output('output.mkv').run(capture_stdout=True, capture_stderr=True)
except ffmpeg.Error as e:
    print(e.stderr.decode())

Without capture_stderr=True, e.stderr is empty and the decode() call fails.

See the command, or skip the package

To see the exact FFmpeg command the package builds, use .compile() where you would use .run(); it returns the command as a list.

The ffmpeg-python package has not had a new release for several years. It still works, because it only builds commands, but for simple jobs Python's own subprocess module does the same with nothing extra to install:

import subprocess
subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-vf', 'scale=1280:-2', 'output_720p.mp4'], check=True)

Common errors

  • FileNotFoundError: 'ffmpeg'. The FFmpeg program is not installed or not on the PATH. Step 1, then a new terminal.
  • module 'ffmpeg' has no attribute 'input'. The wrong package is installed. See step 2.
  • The output has no sound. A filter was applied to the whole input. See step 5.

Long encoding jobs

Encoding uses every CPU core for as long as it runs. For batch jobs, a remote machine keeps your own computer usable: see Encoding RDP plans. If the script lives on GitHub, install GitHub CLI on Windows to fetch it there, and check GPU information in Linux before you try hardware encoding.

Questions

How do I install FFmpeg for Python?

Install the FFmpeg program for your system first, then run pip install ffmpeg-python. The Python package does not include FFmpeg itself.

Why do I get "module ffmpeg has no attribute input"?

A different package named ffmpeg or python-ffmpeg is installed. Uninstall it and install ffmpeg-python.

Can I use FFmpeg in Python without ffmpeg-python?

Yes. Call the ffmpeg command with Python's subprocess.run.

How do I convert MP4 to MP3 in Python?

Use ffmpeg.input('input.mp4').audio.output('audio.mp3').run().