Getting Started With Medusa
Medusa is an open-source automated video library manager for TV shows. It watches new episodes, organizes them automatically, and gives you a decent web interface to browse your collection. It runs on Python and hooks into Usenet and torrent indexers, so you can set it up to fetch and download shows without touching a browser. It started around 2013 as a fork of Sick Beard, which had become unmaintained. The original developer pulled the codebase, rewrote large chunks of it, and rebranded it. Since then it has gone through several maintainers and architecture changes. The current version supports NZBGET, SABNZBD, and a few torrent clients, plus basic metadata scraping from TheTVDB and TVmaze. The main thing it does is sit on your media server and monitor specified series. When a new episode airs, it checks your configured indexer, downloads it, renames the file into a consistent naming scheme, and moves it into your library directory. It also handles quality profiles, so you can skip lower-resolution rips if you have the storage budget.
Installation
The most straightforward path is using the package manager on Linux. For Debian/Ubuntu: Install the dependencies first. You will need python3, git, and a few pip packages. Clone the repository from the official GitHub page, run the install script, and configure it with a simple config file. Windows users can grab a standalone binary from the releases page. It runs as a background service, though you may need to adjust your firewall rules so it can reach external indexers and torrent trackers.
Mac users have a Homebrew formula available. brew install medusa gets you running in about five minutes, though the network setup afterward is the same as everywhere else. I run it on a low-power mini PC with a USB drive for downloads and an SSD for the library. It uses roughly 200MB of RAM idle and peaks higher when processing multiple episodes at once.
Get the Full Details
Configuration
Open the web interface on port 8081 by default. Create an admin account, then go to the Settings tab. This is where you connect your download clients. Go to Settings > Main > General. Scroll down to the download clients section. Select NZBGet or SABnzbd from the dropdown and fill in the host address, port, username, and password. Test the connection. If it fails, check your client's authorization settings and make sure the IP of the Medusa host is whitelisted. Under Settings > Main > Search Providers, add your preferred Usenet or tracker indexers. Most people use NZBgeek, Bad Buzz, or a private tracker with API access. Enter the API key and save. Not every indexer is compatible with the built-in search module, so verify yours is on the supported list before entering your credentials.
This is the part beginners get wrong most often. Go to Settings > Main > Quality. Select a profile for each series or apply one globally. The default profile downloads anything, which means you end up with 480p MP4s for shows that have high-definition releases. Set it to Prefer Premium or Optimal if you want better results. The difference in file size and quality is noticeable within a few episodes. Under Settings > Main > Naming, pick a format. I recommend the extended naming style: Show.Name.S01E01.720p.HDTV.x264. It is clear, sortable, and works with most metadata scrapers. If you use a weird custom format, your library will look inconsistent and sorting by season becomes unreliable. One issue I ran into repeatedly was the episode matching logic. Medusa sometimes matches a show to the wrong series, especially for international titles or shows with similar names. Last year I had a case where it imported an obscure documentary instead of the actual episode I wanted. The workaround is to manually assign the correct show from the list before processing, or use the Show Name field with the exact title from TheTVDB to avoid ambiguity.
Another problem is post-processing. After Medusa downloads an episode, it runs a post-processor to rename and move files. If your library directory has strict permissions, the process fails silently and leaves files in the temp folder. Check the logs under Settings > Main > Logs and look for permission denied errors. Running Medusa under a user account that has write access to both the download folder and the library directory fixes it. Usenet retention is another factor. If your provider has less than 1500 days of retention, you will miss older episodes for shows with long runs. This is not a Medusa problem, but it shows up as missing episodes and people blame the software. Verify your retention period before complaining about gaps in your library.
Using It With Other Tools
Medusa works alongside Radarr for movies, but there is overlap and some tension between the two. They use similar architectures, and running both on the same server is fine, just give them separate download directories and different quality profiles. Do not let them share the same indexer API key unless the indexer supports multiple API keys — many do not, and you will get rate-limited. For metadata and library organization, you can feed the output into Kodi or Jellyfin. Set their library paths to point at the same directories Medusa writes to. It takes about ten minutes to set up the scan, and then both tools stay in sync as long as Medusa keeps the naming consistent.
Limitations
Medusa is not a full Plex replacement. It does not stream content or transcode. It manages files and leaves playback to whatever you already have set up. It also does not support podcasts, audiobooks, or movie libraries natively. If you need those features, you are better off using a dedicated podcast manager or Radarr for films. The web interface works on desktop browsers but the mobile experience is functional at best. There is no native app. Use a browser-based dashboard or set up a reverse proxy with a clean URL if you want to check it from your phone. Updates are not always smooth. Between versions, configuration file formats sometimes change. Back up your config directory before upgrading, and read the release notes for any migration steps. I lost a few custom naming overrides after a major version jump because the old format was deprecated without a warning in the changelog.
If you want something simpler with fewer moving parts, Sonarr handles TV shows with more active development and a larger community. Medusa still works, but the pace of new features has slowed compared to the alternatives. For a stable, no-fuss setup, pick the tool that matches your indexer situation and stick with it rather than switching back and forth.
Key Considerations Before You Start
Make sure your indexer API keys are valid. Check your download client is reachable from the Medusa host. Set quality profiles to something stricter than default. Back up your config before updating. Test with one show first before pointing it at your entire library. The software is free and open source. The download and installation pages are at the official repository. Read the documentation there for the latest configuration options, as the web interface changes slightly between versions.
