Medusa Docker Setup for Automated TV Libraries

Medusa's role in an external TV acquisition pipeline

Medusa solves the coordination problem around keeping a television library current. It is intended for people running their own server or NAS who want scheduled episode acquisition, controlled release selection, consistent file organization, subtitle handling, metadata generation, and media-server updates. It is not a streaming application, an indexer, a torrent service, or a Usenet provider. The README is explicit that Medusa requires external torrent or Usenet providers and a compatible download client, and it does not provide media or access to provider services.

The target user needs more than a server with Python installed. A practical deployment also needs a metadata indexer, one or more authorized search providers, an external download client, storage for completed and temporary files, and a destination library readable by Kodi, Plex, or Emby. Optional integrations can add subtitles, Trakt data, notifications, metadata sources, and post-processing scripts.

This boundary is the project's most important technical characteristic. Medusa is an orchestrator between services rather than a self-contained download solution. If one link in that chain is unavailable, searching, downloading, or library delivery can stop even when Medusa itself is running. The README also asks users to operate it only with services and content they are authorized to access.

Metadata, search, download, and post-processing data flow

The documented workflow is:

Metadata indexer → Search provider → Download client → Post-processing → Media server (Kodi, Plex, and Emby)

Medusa first retrieves show metadata from the selected indexer. TVDBv2, TVmaze, TMDB, and IMDb are named as metadata options, while Trakt, AniDB, and AniList provide related integration or mapping functions. The user can select an indexer per show and change that selection for an existing show.

Medusa then searches configured torrent and Usenet providers. Scheduled search modes include backlog, proper, and repack searches. Manual searches expose release details such as provider, quality, release group, seeders, peers, and publication information, allowing a selection instead of forcing a single automated choice. Caching and processed-result tracking are intended to reduce repeated parsing of releases already seen.

A selected release is sent to an external client. The listed torrent clients are Deluge, Synology Download Station, MLDonkey, qBittorrent, rTorrent, Transmission, and uTorrent. NZB support includes SABnzbd, NZBGet, black-hole, and RSS workflows. Once the client reports completion, Medusa applies its configured naming and sorting rules. Processing can copy, move, hardlink, or symlink the result, clean related files and empty directories, and generate posters, banners, fanart, NFO files, and thumbnails. Kodi, Plex, and Emby can then receive library updates.

This design gives Medusa substantial control over selection and file placement, but it also makes path configuration and service permissions important. Hardlinks and symlinks only work where the relevant paths, filesystems, and service accounts permit them. The README does not document a universal permission recipe, so deployment-specific path checks are necessary.

Installing Medusa with the official Docker image

The README recommends Docker for most server and NAS deployments. The official image name is `pymedusa/medusa`. Based on the documented tag table, `latest` and `master` refer to the `master` branch for stable installations, while `develop` follows the `develop` branch and may be less stable.

The published image supports `linux/amd64`, `linux/arm/v7`, and `linux/arm64`. That makes host architecture an immediate adoption check. A stable server or NAS deployment should use one of the documented stable tags rather than assuming that the newest branch-specific image is appropriate.

The README does not provide the complete `docker run` or Docker Compose configuration. It should not be replaced with guessed flags, volume mounts, ports, or environment variables. Those details are deployment-specific and depend on the download client, temporary directory, configuration persistence, and media-server paths.

For a first real use, start with the official image, configure one monitored show, select a metadata indexer, connect one authorized provider, and configure one compatible download client. Then define the episode processing destination and check the permissions of both the Medusa process and the download client. A manual episode search is the clearest initial operation because the interface presents release details before the user selects a result. After the client completes the download, confirm that Medusa applies the configured naming method and that Kodi, Plex, or Emby sees the new file.

The project also provides a source installation path for developers and unsupported platforms. Its documented requirement is Python 3.9 or later. The repository includes `start.py`, `SickBeard.py`, `setup.py`, `requirements.txt`, and `pyproject.toml`, but the README does not show the complete source quick-start command sequence. The `develop` branch also has workflows for Python backend, Node frontend, and API tests, indicating that source deployment is not limited to a single runtime.

Release parsing, subtitle matching, and library control

Medusa does more than locate and download an episode. Release names are parsed and enriched with GuessIt, including a separate anime-oriented path. Anime workflows can use AniDB mappings and release-group white and blacklists. Per-show controls, quality profiles, and status views are available for missing, wanted, quality-upgrade, and upcoming episodes.

Subtitle handling can run automatically, but users can also search manually and inspect the provider, language, score, and matching information. Medusa can delay post-processing while waiting for required subtitles. That setting is useful when subtitles are part of the acceptance criteria for a release, although it also means that a subtitle provider problem can hold up processing after the video download completes.

File handling is deliberately configurable. The documented methods are copy, move, hardlink, and symlink, alongside optional post-processing scripts. Cleanup can remove associated files and empty directories during replacement or post-processing. These choices affect storage use, ownership, and recoverability. A move consumes the completed download path after processing. A copy duplicates file data unless storage behavior handles it otherwise. Hardlinks can avoid duplication within suitable filesystem constraints, while symlinks introduce another path relationship that must remain valid in the consuming application.

Library replacement also differs by target. Medusa supports library updates for Kodi, Plex, and Emby, with optional Kodi cleanup when replacing existing media. Metadata can be generated per season when the selected indexer supports it, with a full-show update as the fallback. The interface also previews how quality changes affect backlog size, which helps connect a desired quality profile to the number of missing episodes.

Medusa maintenance, dependencies, and license effects

The repository is not archived, and the last push was on 2026-10-07. Recent releases include v1.0.26 on 2026-08-21, v1.0.25 on 2025-11-12, and v1.0.24 on 2025-10-30. The `pyproject.toml` version is `1.0.26`, matching the newest listed release. This supports treating the default branch as receiving recent development, but the README does not publish a fixed support term for any integration or older release.

Upgrades carry dependency and integration costs. The Python package requires Python 3.9 or later and pins many dependencies, including Tornado, requests, PyYAML, `pymediainfo`, `pytrakt`, and `subliminal`. It also downloads `adba`, `pytimeparse`, and `tvdbapiv2` from specific GitHub archives. An isolated Docker deployment can simplify replacement, while a source deployment must manage Python dependencies and any frontend assets.

Integrations also create an ongoing compatibility surface. Changes in an indexer, provider, download client, media server, metadata service, or subtitle source can affect a pipeline even if the Medusa version itself has not changed. The repository contains API tests and backend and frontend workflows, while `package.json` defines `npm run test-api` for the Dredd API test command. The README does not promise compatibility with every version of each external service.

Medusa is distributed under GPL-3.0. That matters when the software is redistributed or incorporated into a distributed work, and when obligations are assessed for a particular deployment. This is not legal advice. Operators should read `COPYING.txt` and assess their own distribution model before modifying or redistributing the application.

Where Medusa is the wrong tool

Medusa is the wrong choice for someone who wants a single application that supplies television content, indexer access, search results, or downloading. Those responsibilities sit with separate services. Even a successful Medusa installation begins with configuration gaps rather than a playable library.

It is also a poor fit for environments where torrent and Usenet acquisition is neither desired nor authorized, or where organizational policy prohibits external download clients. The feature set includes both acquisition methods, but availability does not make either method appropriate for every user.

The orchestration model can also exceed the needs of a small library with a simple naming scheme. Configuring indexers, provider results, clients, metadata profiles, subtitles, notification services, and media-server updates creates several places where incorrect assumptions can affect the final file. A media manager focused on local organization without provider search and external download dispatch may be a better fit. Likewise, a dedicated client with native episode monitoring can be simpler when its supported providers and processing model already match the user's setup.

A credible alternative is to separate acquisition from library organization. A general-purpose download client or RSS-driven Usenet stack can fetch selected files, while a separate automation or media organization tool renames them and updates the library. That arrangement offers finer control over acquisition, but it transfers scheduling, release parsing, show-state, and post-processing work to the user. Medusa is more relevant when that coordination is the problem to solve.

Editorial conclusion

Medusa is suitable for a self-managed television library when the operator already understands indexers, authorized providers, download clients, and filesystem permissions. It is a poor fit for users seeking a standalone media source, a turnkey all-in-one appliance, or a library manager that can operate without external services. Before adoption, verify that the `pymedusa/medusa` image matches the host architecture, that the selected provider and download client are configured correctly, and that Medusa has access to the intended library and temporary download paths. For Docker deployments, `master` and `latest` correspond to the stable branch, while `develop` contains recent changes and may be less stable.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. pymedusa/Medusa on GitHub
4. README
5. Releases