---
id: python-mpv
version: "1.0.8"
license: GPLv2+ or LGPLv2.1+
license_treatment: copyleft
maintenance: aging
---

# python-mpv — A python interface to the mpv media player

License: copyleft · Maintenance: aging · Downloads: 111.6K/mo

## 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 above — verify before relying.

Python ctypes-based interface to the mpv media player, exposing mpv's API for programmatic control of video and audio playback.

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

pip install python-mpv
uv add python-mpv
poetry add python-mpv

## Installing python-mpv

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.

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

libmpv must be installed and discoverable on your system (in PATH on Windows, system library path on Linux/macOS). Python >= 3.9 required.

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_current
- Install friction: low
- Maintenance: aging
- Downloads: 111.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mpv python interface, media player control python, video playback automation, audio player library, ctypes mpv binding, media-player, ctypes-binding, multimedia

[View on SkillFed](https://skillfed.io/packages/python-mpv) · [View on PyPI](https://pypi.org/project/python-mpv/)