python-mpv
A python interface to the mpv media player
Decision gist · record as of 2026-08-14
Yes, if you need programmatic control of mpv playback and can manage the external libmpv dependency. The package is stable and production-ready, with low install friction and no Python dependencies. However, the 476-day release gap and known macOS event-handling issues warrant checking current compatibility with your mpv version and target platform before committing to production use.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- libmpv must be installed and discoverable on your system (in PATH on Windows, system library path on Linux/macOS).
- Python >= 3.9 required.
- Low install friction; pure Python wheel with no runtime dependencies.
License · maintenance · safety
GPLv2+ or LGPLv2.1+ (copyleft) — Dual-licensed under GPLv2+ or LGPLv2.1+ (copyleft). Users must comply with GPL or LGPL terms; commercial use requires careful license review or relicensing negotiation.
last release 2025-04-25 (476 days) · last repo commit 2025-04-25 · 631 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 111,608 downloads/mo, #12,408 on PyPI
Alternatives
Verify before relying
import mpv
player = mpv.MPV(ytdl=True)
player.play('https://youtu.be/DOmdB7D-pUU')
player.wait_for_playback()- Whether the 476-day release gap reflects active maintenance or de facto dormancy
- Current compatibility status with recent mpv releases and their API changes
- Stability of event handling on macOS (documentation mentions known bugs in event logic)
What it is and what it does
python-mpv is a Python wrapper around libmpv, the mpv media player's C library, using ctypes to expose mpv's full command and property API. It lets you programmatically control video and audio playback—play files or streams, adjust properties like fullscreen and volume, bind keyboard shortcuts, capture screenshots, and handle playback events—all from Python code.
The package is single-file and self-contained, with no Python runtime dependencies; you only need libmpv installed on your system. It handles threading internally for event processing, though you can disable that and integrate with external event loops if needed. The API closely mirrors mpv's native input commands and properties, so the mpv manual is your primary reference for what you can do.
Use it for
- Build a media player application with custom UI by controlling mpv playback and reading properties like time position and metadata
- Automate video or audio processing workflows that need frame-accurate playback control or filter chain manipulation
- Create a playlist manager or streaming client that plays URLs (including YouTube via youtube-dl) programmatically
- Capture screenshots or overlays from video during playback for analysis or annotation
- Integrate mpv playback into a larger Python application without reimplementing media handling
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes, if you need programmatic control of mpv playback and can manage the external libmpv dependency.
The package is stable and production-ready, with low install friction and no Python dependencies. However, the 476-day release gap and known macOS event-handling issues warrant checking current compatibility with your mpv version and target platform before committing to production use.
Install
python-mpv on PyPI
Before you install
Low install friction; pure Python wheel with no runtime dependencies. Maintenance is aging (476 days since last release), though the repository remains active and the package is marked Production/Stable. Requires libmpv as an external system library.
libmpv must be installed and discoverable on your system (in PATH on Windows, system library path on Linux/macOS). Python >= 3.9 required.
License in practice
Dual-licensed under GPLv2+ or LGPLv2.1+ (copyleft). Users must comply with GPL or LGPL terms; commercial use requires careful license review or relicensing negotiation.
Quickstart
import mpv
player = mpv.MPV(ytdl=True)
player.play('https://youtu.be/DOmdB7D-pUU')
player.wait_for_playback()Verify before relying
- Whether the 476-day release gap reflects active maintenance or de facto dormancy
- Current compatibility status with recent mpv releases and their API changes
- Stability of event handling on macOS (documentation mentions known bugs in event logic)
Package facts
| License | GPLv2+ or LGPLv2.1+ copyleft |
| Python support | Supports the current Python release >=3.9 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | None |
| Maintenance | Aging 476 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 111,608 / month, #12,408 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableEnvironment :: X11 ApplicationsIntended Audience :: DevelopersLicense :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)License :: OSI Approved :: GNU Lesser General Public License v2 or later (LGPLv2+)Natural Language :: EnglishOperating System :: POSIXProgramming Language :: CProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.9Topic :: Multimedia :: Sound/Audio :: PlayersTopic :: Multimedia :: Video :: Display |
Evidence: python_mpv-1.0.8-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “mpv python interface”
- python-mpvPython ctypes-based interface to the mpv media player, exposing mpv's…
- python-interfaceDeclares interfaces and statically asserts that classes implement…
- zope.interfaceProvides a Python implementation of object interfaces for declaring…
Give your agent the search over MCP, or paste the wish link into any chat.
More Video packages
yt-dlp downloads audio and video from thousands of sites via a command-line interface, supporting format selection, metadata modification, and post-processing.
Install it if you need to download video or audio from the web.
MoviePy is a Python library for video editing that reads, processes, and writes video and audio files by converting them to numpy arrays for frame-level manipulation and effect application.
Generate access tokens and call LiveKit server APIs (room management, egress, ingress, SIP, agent dispatch, connectors) from Python backends using async/await.
Install it if you are building a backend that needs to generate tokens, manage rooms, or integrate with LiveKit's services.
pytube downloads YouTube videos and playlists to local files via Python API or command-line interface, with support for multiple stream formats and quality levels.
A framework for building realtime multimodal and voice AI agents that connect to LiveKit rooms and handle audio/video interactions with language models.
ffmpy is a Python wrapper around FFmpeg that lets you build and execute FFmpeg command lines programmatically without writing shell commands directly.
See also python-vlc · ffmpeg-python · typed-ffmpeg · pyobjc-framework-MediaPlayer · pyobjc-framework-AVKit · pyfmodex · opencv-python · casttube · opencv-contrib-python