Install & Compatibility
Where this runs
tested against v2.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 112.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.6s · import 0.592s · 184MB
151MB installed
● package 151MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VideoFileClip
✓ from moviepy import VideoFileClip
✗ from moviepy.editor import VideoFileClip
This quickstart demonstrates how to load a video, create text clips for an intro and outro, concatenate them with the original video, and export the result. It highlights using `VideoFileClip`, `TextClip`, and `concatenate_videoclips` from `moviepy.editor`. Remember to replace 'my_video.mp4' with an actual video file and ensure FFmpeg is correctly installed.
from moviepy.editor import VideoFileClip, concatenate_videoclips, TextClip, CompositeVideoClip
def create_intro_outro(video_path='my_video.mp4'):
try:
clip = VideoFileClip(video_path)
intro_text = TextClip("My Awesome Video", fontsize=70, color='white', bg_color='black')\
.set_duration(2).set_position('center')
outro_text = TextClip("Thanks for Watching!", fontsize=50, color='yellow', bg_color='black')\
.set_duration(1.5).set_position('center')
# Ensure text clips match video resolution for smooth concatenation
intro_text = intro_text.set_fps(clip.fps).resize(newsize=clip.size)
outro_text = outro_text.set_fps(clip.fps).resize(newsize=clip.size)
final_clip = concatenate_videoclips([intro_text, clip, outro_text], method="compose")
output_filename = video_path.replace('.mp4', '_with_intro_outro.mp4')
final_clip.write_videofile(output_filename, fps=clip.fps, threads=4)
print(f"Video saved to {output_filename}")
clip.close()
intro_text.close()
outro_text.close()
final_clip.close()
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure 'my_video.mp4' exists and FFmpeg is installed and in your PATH.")
# To run, ensure you have a video file named 'my_video.mp4' in the same directory
# create_intro_outro()
Debug
Known issues
breakingMoviePy's core functionality relies on FFmpeg. You MUST have FFmpeg installed on your system and accessible in your environment's PATH. Without it, most video loading and saving operations will fail with 'OSError: MoviePy Error: the file `ffmpeg` could not be found.'fixInstall FFmpeg for your operating system (e.g., `brew install ffmpeg` on macOS, or download binaries for Windows/Linux). Verify installation by running `ffmpeg -version` in your terminal. For Python, `pip install imageio-ffmpeg` is highly recommended, as it helps manage FFmpeg processes but does not install the FFmpeg binaries themselves.
affects: All versions
gotchaProcessing large video files can be extremely memory-intensive and slow. MoviePy often loads frames into memory, leading to out-of-memory errors or very long processing times on longer or high-resolution videos.fixOptimize by processing smaller clips, applying resizing early (`clip.resize()`), setting `fps` and `threads` parameters in `write_videofile`, and using generators for long sequences. Always `close()` clips when done with them to release resources, especially in loops.
affects: All versions
gotchaAudio and video synchronization issues can occur, especially with variable frame rate (VFR) source videos or after complex edits. Output files might have desynchronized audio.fixEnsure source videos are constant frame rate (CFR) if possible. When writing, try different codecs or explicitly setting audio parameters. For difficult cases, you might need to extract audio, process video, and then remux them separately (e.g., using FFmpeg directly or with `clip.set_audio(AudioFileClip('path_to_audio.mp3'))`). affects: All versions
deprecatedSeveral modules and functions were restructured or deprecated between MoviePy 1.0 and 2.x (e.g., `moviepy.video.tools.cuts`). While many core functionalities remain similar, older tutorials or code snippets might use deprecated paths or methods.fixRefer to the official MoviePy 2.x documentation for the most up-to-date API. Prioritize imports from `moviepy.editor` as it's the stable high-level interface. For specific changes, consult the MoviePy changelog.
affects: Versions <= 1.x migrating to 2.x
Upgrade
Version history
2.2.1latest on PyPI · released May 21, 2025
Audit
Dependencies
ffmpegrequiredMoviePy relies heavily on FFmpeg for video processing. FFmpeg binaries must be installed and accessible in your system's PATH, or its location specified via `FFMPEG_BINARY` environment variable. `imageio-ffmpeg` (an optional Python dependency) helps manage FFmpeg subprocesses.
imageio-ffmpegoptionalRecommended for robust FFmpeg integration and handling various video codecs.
PillowoptionalUsed for image manipulation tasks within MoviePy (e.g., text clips, overlays).
numpyrequiredFundamental for numerical operations on video frames.