Download

PySceneDetect is completely free software, and can be downloaded from the links below. See the license and copyright information page for details. If you have trouble running PySceneDetect, ensure that you have all the required dependencies listed in the Dependencies section below.

PySceneDetect requires at least Python 3.10 or higher.

Install via pip      

pip install --upgrade scenedetect

pip install --upgrade scenedetect-headless

PySceneDetect is available via pip as two packages:

• scenedetect: full install with the CLI, depends on opencv-python
• scenedetect-headless: full install with the CLI, depends on opencv-python-headless (servers/containers without GUI libraries)

Both provide the same scenedetect Python module -- install only one of them.

Windows Build (64-bit Only)  

Docker Image  

Official container images are published at ghcr.io/breakthrough/pyscenedetect. The image includes the full CLI, all optional backends (PyAV, MoviePy), and the external tools used for video splitting (ffmpeg, mkvmerge) -- no other setup is required:

docker pull ghcr.io/breakthrough/pyscenedetect
docker run --rm ghcr.io/breakthrough/pyscenedetect version

To process videos, mount the folder containing them into the container (the image runs as a non-root user, so output files are written with regular permissions):

docker run --rm -v "$(pwd):/files" ghcr.io/breakthrough/pyscenedetect \
    -i /files/video.mp4 detect-adaptive split-video -o /files

The latest tag (the default when no tag is given) points to the most recent recommended build, the main tag tracks the development branch, and version tags (e.g. 0.7.1) point to specific releases. podman can be used in place of docker in the commands above.

Post Installation

After installation, you can call PySceneDetect from any terminal/command prompt by typing scenedetect (try running scenedetect --help, or scenedetect version). If you encounter any runtime errors while running PySceneDetect, ensure that you have all the required dependencies listed in the System Requirements section above (you should be able to import numpy and import cv2). If you encounter any issues or want to make a feature request, feel free to report any bugs or share some feature requests/ideas on the issue tracker and help make PySceneDetect even better.

Dependencies

Python Packages

PySceneDetect requires Python 3 and the following packages, all of which the scenedetect and scenedetect-headless packages install automatically:

• OpenCV: pip install opencv-python (any opencv-python* variant works)
• Numpy: pip install numpy
• Click: pip install click (command-line interface only)
• tqdm: pip install tqdm (optional, enables progress bars)
• platformdirs: pip install platformdirs (command-line interface only)

Optional packages:

• PyAV: pip install av

Video Splitting Tools

For video splitting support, you need to have one of the following tools available (included in Windows builds):

• ffmpeg, required to split video files (split-video or split-video -c/--copy)
• mkvmerge, part of mkvtoolnix, command-line tool, required to split video files in stream copy mode (split-video -c/--copy only)

The ffmpeg and/or mkvmerge command must be available system wide (e.g. in a directory in PATH, so it can be used from any terminal/console by typing the command), or alternatively, placed in the same directory where PySceneDetect is installed. On Windows this is usually C:\PythonXY\Scripts, where XY is your Python version. For more information, see the CLI documentation.

Building OpenCV from Source

If you have installed OpenCV using pip, you will need to uninstall it before installing a different version of OpenCV, or building and installing it from source.

You can click here for a quick guide (OpenCV + Numpy on Windows & Linux) on installing OpenCV/Numpy on Windows (using pre-built binaries) and Linux (compiling from source). If the Python module that comes with OpenCV on Windows is incompatible with your system architecture or Python version, see this page to obtain a pre-compiled (unofficial) module.

To ensure you have all the requirements installed, open a python interpreter, and ensure you can run import numpy and import cv2 without any errors.

Code Signing Policy

This program uses free code signing provided by SignPath.io, and a free code signing certificate by the SignPath Foundation