MoviePy: Python Video Editing Through a NumPy-Based Clip API

What MoviePy Solves and Who It Is For

Video editing in Python before MoviePy meant calling ffmpeg through subprocess and managing raw process arguments. MoviePy wraps that work in a Python API where clips are objects and effects are functions. The README describes the core use cases as cuts, concatenations, title insertions, video compositing (non-linear editing), video processing, and creation of custom effects.

The library suits developers who need to automate video production, researchers who generate visualizations, and anyone who wants to define an effect as Python code rather than a filter graph. It runs on Windows, Mac, and Linux, requires Python 3.9 or newer, and handles GIF output as well as standard video and audio formats. The README and the pyproject.toml classify it under the Topic :: Multimedia :: Video and Topic :: Multimedia :: Sound/Audio categories, reflecting the dual audio-and-video scope.

How MoviePy Works Under the Hood

The README explains the mechanism directly: MoviePy imports media frames and audio into NumPy arrays so that every pixel is accessible from Python. Effects are defined by writing functions that transform those arrays. After compositing, the final clip is encoded back to the desired format using ffmpeg.

This design makes it easy to write a custom effect in a few lines of Python, but it also means the data has to pass through Python for every frame. The README acknowledges the consequence: MoviePy is slower than calling ffmpeg directly because of the heavier data import and export operations. For batch jobs on long videos, this overhead is worth measuring before committing to the library.

Installing MoviePy and Running the First Example

Install the library with pip:

pip install moviepy

For development, clone the repository and install in editable mode:

pip install -e .

The Dockerfile shows that ffmpeg is installed via the system package manager before MoviePy is set up, which is the required system dependency. The README directs readers to the online documentation for installation variations such as a custom ffmpeg path or preview support.

The README gives a concrete example: load a video file, trim it to a ten-second subclip, scale the audio, add a centered text overlay, and write the result to a new file:

from moviepy import VideoFileClip, TextClip, CompositeVideoClip

# Load file example.mp4 and keep only the subclip from 00:00:10 to 00:00:20
# Reduce the audio volume to 80% of its original volume

clip = (
    VideoFileClip("long_examples/example2.mp4")
    .subclipped(10, 20)
    .with_volume_scaled(0.8)
)

# Generate a text clip. You can customize the font, color, etc.
txt_clip = TextClip(
    font="Arial.ttf",
    text="Hello there!",
    font_size=70,
    color='white'
).with_duration(10).with_position('center')

The method names reflect the v2 API. The chained .subclipped(), .with_volume_scaled(), and .with_position() calls are part of the v2 interface, not the v1 API.

V2 and the Breaking Changes from V1

MoviePy v2.0 introduced major breaking changes from v1. The README warns about this at the top and notes that v1 is no longer maintained, with the last v1 docs available at a separate versioned URL. The project points to a migration guide for developers moving code from v1 to v2.

The v2 API renames many methods. The example in the README shows methods like .subclipped() and .with_volume_scaled() that did not exist in v1. Any existing MoviePy codebase targeting v1 requires auditing before upgrading. The pyproject.toml lists the current release as v2.2.0, with v2.2.1 released on 2025-05-21.

Dependencies and Optional Extras

The pyproject.toml lists MoviePy's core dependencies: decorator, imageio, imageio_ffmpeg, numpy (1.25 or newer), proglog, python-dotenv, pillow (9.2 or newer), and opencv-python-headless. The imageio_ffmpeg package handles ffmpeg integration, which means ffmpeg does not need to be on the system PATH in the typical installation.

Optional extras are available for documentation generation (numpydoc, Sphinx, pydata-sphinx-theme), testing (coveralls, pytest-cov, pytest), and linting (black, flake8, isort, pre-commit). Install the doc extras with pip install "moviepy[doc]" for local documentation builds. The project supports Python 3.9 through 3.12 based on the classifier entries in pyproject.toml.

Limitations: Speed, the moviepy.editor Module, and Maintenance

The most important limitation is speed. The README states explicitly that MoviePy is slower than using ffmpeg directly, because every frame passes through Python and NumPy. Long videos or high-resolution exports will show this cost.

The v1 to v2 migration removed the moviepy.editor convenience import that many tutorials reference. Code that tries from moviepy.editor import VideoFileClip will fail on v2. The README does not document a compatibility shim for this.

The last release in the repository was v2.2.1 on 2025-05-21. The last push to the master branch was on 2026-08-26. The README lists four active maintainers and includes a note that the project is seeking additional contributors.

ffmpeg-python is an alternative that also wraps ffmpeg in a Python API but works by constructing ffmpeg filter graphs rather than pulling frames into NumPy arrays. It does not give per-pixel access in Python but runs at ffmpeg's native speed, making it a better fit for straightforward transcoding pipelines where custom frame-level effects are not needed.

Licence and Community

MoviePy is released under the MIT licence and is hosted on GitHub at Zulko/moviepy. The README credits Zulko as the original author and notes that @osaajani led the v2 development with the linked pull request. Active maintainers at the time of the last README update are Zulko, @osaajani, @tburrows13, and @keikoro. The README also lists past maintainers. A Reddit channel is the recommended place for usage questions and examples.

Documentation is built automatically from every push to the master branch and hosted at the project documentation site at zulko.github.io/moviepy. To build the docs locally, install the doc extras with pip install "moviepy[doc]" and run make html from the docs directory. The project uses pre-commit for code quality checks. The lint extras (black, flake8, flake8-docstrings, isort) are available via pip install "moviepy[lint]" for contributors who want matching local tooling.

The pyproject.toml marks the project as Development Status: 5 - Production/Stable, which aligns with the v2.x versioning. The last release (v2.2.1) was published on 2025-05-21; the last push to the master branch was on 2026-08-26.

Editorial conclusion

MoviePy fits Python developers who need to automate video editing, compose clips from Python data, or define custom frame-level effects without writing C. The slower-than-ffmpeg tradeoff is a real cost for high-volume batch processing. Teams that upgraded from v1 must check the v1-to-v2 migration guide at the project documentation, because v2 introduced breaking API changes. The last release was v2.2.1 on 2025-05-21; the last push to the repository was on 2026-08-26.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Zulko/moviepy on GitHub