---
id: mediapy
version: "1.2.7"
license: unclear
license_treatment: permissive
maintenance: active
---

# mediapy — Read/write/show images and videos in an IPython notebook

License: permissive · Maintenance: active · Downloads: 1.1M/mo

## What it is and what it does

Mediapy is a library that integrates image and video I/O directly into IPython and Jupyter notebook environments. It wraps common operations—reading from URLs or files, displaying with optional sizing and titles, writing to disk—and returns media as numpy arrays so you can manipulate them with standard scientific Python tools. The library handles metadata like video framerate automatically and provides both high-level convenience functions (show_image, read_video) and lower-level streaming interfaces (VideoReader, VideoWriter) for frame-by-frame processing.

The package depends on matplotlib, numpy, and Pillow for image handling, plus ipython for notebook integration. Video I/O requires ffmpeg to be installed on your system PATH. It targets modern Python versions and is designed specifically for notebook workflows, making it most useful when you're already working interactively in Jupyter rather than in scripts.

Use it for:

- Display images fetched from URLs or local files directly in a notebook cell with optional height and title parameters.
- Read video files and play them back in a notebook with correct framerate, or extract individual frames as numpy arrays.
- Process video frame-by-frame using VideoReader/VideoWriter to apply transformations and save the result.
- Show multiple images side-by-side in a notebook grid for visual comparison of results.
- Generate synthetic test images or videos programmatically and display them immediately for inspection.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Mediapy reads, writes, and displays images and videos directly in IPython and Jupyter notebooks, returning them as numpy arrays for further processing.

Yes, if you work in Jupyter or IPython notebooks and need to display or manipulate images and videos. The low install friction, active maintenance, permissive license, and tight integration with the notebook environment make it a straightforward choice. The only gotcha is the ffmpeg system dependency for video I/O, which is documented and typically a one-time setup.

## Install

pip install mediapy
uv add mediapy
poetry add mediapy

## Installing mediapy

Before you install: Low friction install with four common runtime dependencies (ipython, matplotlib, numpy, Pillow). Actively maintained with a recent release 44 days ago.

License in practice: Licensed under Apache Software License (permissive), allowing use in most commercial and open-source projects without significant restriction.

Quickstart:

pip install mediapy
import mediapy as media
import numpy as np

image = media.read_image('https://github.com/hhoppe/data/raw/main/image.png')
media.show_image(image)

video = media.read_video('https://github.com/hhoppe/data/raw/main/video.mp4')
media.show_video(video)

Video I/O requires ffmpeg to be installed and present in the system PATH; on Unix this can be installed via apt install ffmpeg.

Verify before relying:

- Whether ffmpeg installation on Windows is straightforward or requires additional setup steps beyond the Unix apt install shown in the docs.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

jupyter notebook image display, video playback in jupyter, read write images numpy, notebook media viewer, ipython image video tools, jupyter-integration, media-io

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