---
id: wagtailmedia
version: "0.18.1"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# wagtailmedia — A Wagtail module for audio and video files.

License: permissive · Maintenance: active · Downloads: 141.1K/mo

## What it is and what it does

wagtailmedia extends Wagtail CMS with first-class support for audio and video files, mirroring the built-in document handling. It provides a Media model, a media chooser panel for page fields, and StreamField blocks for embedding audio and video directly in page content. The package integrates into Wagtail's admin interface and supports customization through settings (configurable file extensions, custom Media models, and form bases) and hooks for queryset filtering.

You install it into a Django+Wagtail project, add it to INSTALLED_APPS, run migrations and collectstatic, then use MediaChooserPanel on ForeignKey fields or AudioChooserBlock/VideoChooserBlock in StreamField definitions. It handles file type detection, provides a browsable media library in the admin, and can expose media via Wagtail's REST API. The package requires Python 3.10, 3.11, 3.12, 3.13, 3.14, Django 5.2 or 6.0, and Wagtail 7.0, 7.1, 7.2, 7.3, 7.4.

Use it for:

- Add a featured audio or video field to blog posts or news articles using MediaChooserPanel
- Build a podcast or video gallery page with StreamField audio/video blocks
- Create a media library interface for content editors to upload and manage audio/video files
- Expose media items through Wagtail's REST API for headless CMS consumption
- Customize media handling by extending AbstractMedia or AbstractMediaChooserBlock

## Worth the install?

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

Adds audio and video file management to Wagtail CMS, providing a media library interface and chooser panels similar to Wagtail's document handling.

Yes. wagtailmedia is actively maintained, has no known vulnerabilities, installs with minimal friction, and solves a clear gap in Wagtail's core (audio/video management). It is well-suited for Wagtail projects that need media beyond documents. The BSD-3-Clause license is permissive. Install if your Wagtail site requires audio or video content management.

## Install

pip install wagtailmedia
uv add wagtailmedia
poetry add wagtailmedia

## Installing wagtailmedia

Before you install: Low install friction; pure Python wheel with only Wagtail and Django as runtime dependencies. Active maintenance with recent release and steady repository activity.

License in practice: BSD-3-Clause is permissive; you may use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install wagtailmedia

# In settings.py
INSTALLED_APPS = [
    "wagtailmedia",
]

# In your page model
from wagtailmedia.edit_handlers import MediaChooserPanel
featured_media = models.ForeignKey("wagtailmedia.Media", null=True, blank=True, on_delete=models.SET_NULL)
content_panels = Page.content_panels + [MediaChooserPanel("featured_media")]

Requires Python >=3.10, Django 5.2 or 6.0, and Wagtail 7.0 or later; must run migrations and collectstatic after installation.

Verify before relying:

- Whether the media model supports custom metadata fields beyond what the documentation shows
- Performance characteristics when managing large media libraries
- Compatibility with third-party Wagtail plugins or custom admin extensions

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 141.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

wagtail audio video management, wagtail media library, wagtail media chooser panel, audio video cms integration, wagtail streamfield media blocks, wagtail media model, wagtail-extension, media-management, cms

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