Medusa

Medusa is a self-hosted automatic video library manager for TV shows. It monitors configured shows, searches supported Usenet and torrent providers, sends releases to configured download clients, and organizes completed episodes with configurable metadata, subtitles, and post-processing.

On this page: Features · Installation · Updating · Support · Security · Contributing

Project links: Wiki · FAQ · Issues · GitHub Discussions · Discord · Reddit · Changelog

How it works

Medusa retrieves show metadata from the selected indexer, searches configured torrent and Usenet providers, sends the selected release to an external download client, and then renames, organizes, enriches, and notifies your media library.

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

[!NOTE] Medusa requires external torrent or Usenet providers and a compatible download client. It does not provide media or access to provider services.

Use Medusa only with services and content that you are authorized to access.

Features

Search and downloads

• Automatic scheduled torrent and Usenet searches, including backlog, proper, and repack searches.
• Manual episode and season-pack searches with detailed selectable results. Users can compare provider, quality, release group, seeders, peers, and publication information before snatching.
• Torrent client integrations include Deluge, Synology Download Station, MLDonkey, qBittorrent, rTorrent, Transmission, and uTorrent.
• NZB integrations include SABnzbd and NZBGet, with black-hole and RSS-based workflows. NZBGet duplicate handling supports DupeKey and DupeScore.
• Configurable download clients, failed-download tracking, and retry support.
• Support for specials, season packs, and multi-episode releases.
• Provider caching and processed-result tracking reduce repeated parsing of previously seen releases.

Metadata and episode management

• Metadata support through TVDBv2, TVmaze, TMDB, and IMDb, with external identifier mappings and integrations for services such as AniDB, Trakt, and AniList.
• Per-show indexer selection and the ability to change an existing show indexer.
• Posters, banners, fanart, NFO, and thumbnail metadata generation.
• Trakt watchlist import and collection synchronization.
• Air-date and DVD ordering support.
• XEM scene numbering and mappings.
• Bulk episode status management and views for missing, wanted, quality-upgrade, and upcoming episodes.

Parsing, anime, and subtitles

• Release-name parsing and enrichment using GuessIt, including anime-specific parsing.
• AniDB integration for anime-related mappings and metadata workflows.
• Anime release-group white- and blacklists.
• Automatic subtitle matching and downloading.
• Manual subtitle search with provider, language, score, and matching details when automatic selection is not suitable.
• Optional delay of post-processing until required subtitles are available.

Post-processing and library integration

• Configurable renaming and sorting with copy, move, hardlink, and symlink processing methods.
• Additional post-processing script support.
• Cleanup of associated files and empty directories during replacement and post-processing.
• Interactive explanations for Allowed and Preferred quality profiles.
• Preview of how quality changes affect backlog size.
• Kodi, Plex, and Emby library updates, plus optional Kodi library cleanup when replacing existing media.
• Per-season metadata updates when supported by the selected indexer, with automatic full-show fallback.

Notifications and integrations

Notifications through Kodi, Plex, Emby, Discord, Slack, Telegram, email, Trakt, Pushbullet, Pushover, and other supported services.

Installation

Docker is the recommended installation method for most server and NAS deployments. Source installation remains useful for developers and unsupported platforms.

Docker

The official image is pymedusa/medusa on Docker Hub. It is built from this repository and published for linux/amd64, linux/arm/v7, and linux/arm64.

The container listens on port 8081 and uses these volumes:

Environment variables:

Minimal Docker Compose example:

services:
  medusa:
    image: pymedusa/medusa:latest
    container_name: medusa
    ports:
      - "8081:8081"
    environment:
      PUID: "1000"
      PGID: "1000"
      TZ: "Etc/UTC"
    volumes:
      - ./config:/config
      - ./downloads:/downloads
      - ./tv:/tv
      - ./anime:/anime
    restart: unless-stopped

A community-maintained alternative is available from LinuxServer.io (lscr.io/linuxserver/medusa). It currently publishes amd64 and arm64 images.

From source

Python 3.9 or later is required. Python 3.9 through 3.13 is currently tested in CI.

You also need Git. MediaInfo is recommended for richer video metadata extraction. UnRAR (or a compatible RAR extractor) is recommended when processing archived downloads. Using a virtual environment is strongly recommended.

Linux/macOS quick start:

git clone --branch master --single-branch https://github.com/pymedusa/Medusa.git
cd Medusa

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python start.py

Open http://localhost:8081 after startup.

Use the develop branch only for testing unreleased changes.

On Windows, create and activate a virtual environment with py -m venv .venv and .venv\Scripts\Activate.ps1 before installing requirements. A minimal equivalent setup is:

git clone --branch master --single-branch https://github.com/pymedusa/Medusa.git
cd Medusa

py -m venv .venv
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python start.py

A systemd service template is available in runscripts/init.systemd for Linux installations.

Other platforms and community packages

Platform-specific installers and NAS packages may be maintained by community projects. Check their documentation and maintenance status before installing.

• Windows setup guidance: Installation and configuration guides
• NAS and community packages (including Synology, QNAP, Asustor): Installation and configuration guides

Detailed installation guides

Use the wiki for detailed installation instructions, Windows setup, Linux service setup, NAS packages, upgrades, migrations, reverse proxy setups, and troubleshooting.

Some older platform-specific wiki pages may require updates. Verify package and dependency versions before following legacy instructions.

Release channels

The Docker develop tag tracks recent changes from the develop branch and may be less stable than latest.

Updating

• Docker users should pull the selected image tag and recreate the container.
• Source installations should back up their configuration before updating the Git checkout.
• Users tracking develop should expect unreleased changes.

Documentation and support

• Wiki
• Installation and configuration guides
• FAQ
• Supported providers
• Using Jackett with Medusa
• Use the issue tracker for reproducible bugs.
• Use the filtered feature request list to review or propose enhancements.
• Use GitHub Discussions, Discord, or the PyMedusa subreddit for usage questions and community discussion.
• Changelog and GitHub Releases

Backup and upgrades

Back up the complete configuration directory and all database files before upgrading, changing branches, testing a development build, or migrating from another application. Follow the relevant migration documentation before modifying or deleting database files.

Users migrating from SickBeard or SickRage can find guidance in the installation guide.

Security

Please report security vulnerabilities through GitHub's private vulnerability reporting. Do not disclose sensitive vulnerability details in a public issue.

Contributing

Contributions are welcome. Create a focused branch from the appropriate upstream branch and read CONTRIBUTING.md before opening a pull request. Please follow the Code of Conduct.

Developer resources include the source-controlled API v2 contract.

License

Medusa is licensed under the GNU General Public License v3.0. See COPYING.txt.

Acknowledgements

LinuxServer.io maintains a community Docker image for Medusa.

Service icons are sourced from Simple Icons and are used only to identify their respective services.

Medusa can use MediaInfo to improve video metadata extraction. MediaInfo is optional for source installations and is included in the official Docker image.