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

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().