namarr

The self-hosted renamer for movies, series and anime: a FileBot alternative for your home server. FileBot-style media matching and ReNamer-style rules in one web UI, in a Docker container. Every change starts as a preview, and every change can be undone.

Features • Metadata • Quick start • AI agents • Documentation • Contributing

💡 How it works

1. Point it at a folder: downloads, an old collection, photos or music.
2. Check the preview: namarr matches every file against TMDB, TheTVDB, TVmaze or AniDB (or applies your rules) and shows old → new. Nothing moves yet.
3. Rename, and undo it any time, per file or per job.

One container for your home server: FileBot-style matching for movies, series and anime, ReNamer-style rules for everything else. Names come out in the format Plex, Jellyfin, Emby or Kodi expect, or in your own.

✨ Features

🎬 Movies, series, anime	Matching against TMDB, TheTVDB, TVmaze and AniDB · IDs in folder names ({tmdb-1399}, [tvdbid-72073]) · ffprobe for names without resolution or codec
✏️ Rules for everything else	16 ReNamer-style rules (replace, regex, numbering, clean up …) · photos by EXIF date · music by tags · rule sets as YAML
🧩 Naming formats	Template language with live example · built in: Plex, Jellyfin, Emby, Kodi · own formats per kind · detect the format of your existing library
🔍 Preview & undo	Test mode by default · diff view, keyboard control · conflicts incl. keep better (resolution, HDR, codecs, audio) · undo per file, job or point in time
🤖 Automation	Watch folders that wait for finished downloads · inbox for uncertain matches · hook for qBittorrent, SABnzbd, NZBGet · MCP server for AI agents
📚 Libraries	One default folder each for movies and series · move, copy or rename in place · folder browser for every path
🔔 After a job	Library refresh for Jellyfin, Emby, Plex · notifications via ntfy, Gotify, Telegram, Discord, webhook
🌍 UI	English and German, including every server message

🗂️ Metadata sources

Source	Movies	Series	Anime	Access
TMDB	✅	✅	✅	your own API key
TheTVDB	✅	✅	✅	API key, plus PIN for a user-supported key
TVmaze		✅		none, free
AniDB			✅	registered client

Series and movies can come from different sources, and every watch folder can pick its own series source, for example AniDB for an anime folder. Details: Metadata sources.

🐳 Quick start

mkdir namarr && cd namarr
curl -o compose.yml https://raw.githubusercontent.com/firsttris/namarr/main/docker/compose.example.yml
# set NAMARR_TOKEN and your media mount, then
docker compose up -d

Open http://localhost:8420, sign in with your token, then under Settings add your folders (/data, or your download, movie and series mounts) and a TMDB API key, or set up one of the other sources.

docker run -d --name namarr --restart unless-stopped \
  -p 8420:8420 \
  -e PUID=1000 -e PGID=1000 \
  -e NAMARR_TOKEN="$(openssl rand -hex 24)" \
  -v ./config:/config \
  -v /mnt/data:/data \
  tristanteu/namarr:latest

mkdir -p ~/.config/containers/systemd ~/namarr/config
curl -o ~/.config/containers/systemd/namarr.container https://raw.githubusercontent.com/firsttris/namarr/main/docker/quadlet/namarr.container
# adjust /mnt/data in namarr.container, then
printf 'a-long-token' | podman secret create namarr-token -
systemctl --user daemon-reload && systemctl --user start namarr

Use the template in docker/unraid/namarr.xml.

Volume	Content
/config	SQLite database
/data	your downloads and your library (or one mount each, see the installation guide)

Environment variables, image tags, updates and the API are in the installation guide.

🤖 AI agents

namarr is an MCP server: an agent such as Claude Code previews, corrects, renames and undoes like you do in the workbench. Nothing moves without an explicit execute_job, and NAMARR_MCP=readonly leaves out every tool that changes files.

claude mcp add --transport http namarr http://localhost:8420/api/mcp --header "Authorization: Bearer $NAMARR_TOKEN"

Tools and setup for other clients: AI agents (MCP).

📸 Screenshots

📚 Documentation

The full documentation is a website with search: firsttris.github.io/namarr. The same pages are in docs/ here on GitHub.

Installation	Compose, docker run, Quadlet, Unraid, folders, environment variables, image tags, updates and backup, health and events
Workbench	preview, actions, conflicts and keep better, undo, template language, naming formats and detecting them from a library, rules
Automation	watch folders, inbox, download client hook, AI agents (MCP), library refresh, notifications
Metadata sources	TMDB, TheTVDB, TVmaze, AniDB, IDs in folder names, languages, episode order
Development	setup, checks, architecture, tests, parser corpus, roadmap

🛠️ Development

Requires Bun 1.4.

git clone https://github.com/firsttris/namarr
cd namarr
bun install
NAMARR_DEMO=1 bun run dev   # http://localhost:8420 with an offline demo catalog

Stack: Bun, TanStack Start (React, server functions), TanStack Query and Virtual, Tailwind, SQLite with Drizzle, Vitest and Playwright. More in Development.

🤝 Contributing

A release name that namarr parses wrong is the most useful issue there is: add it to packages/core/test/corpus/releases.yaml or paste it into an issue. Pull requests are welcome; please run bun run lint, bun run typecheck and bun run test before opening one.

---

⭐ Like namarr? A star on GitHub helps others find it. 🐛 Report a bug · 💡 Request a feature

License: AGPL-3.0 · © Tristan Teufel and contributors Changed versions you pass on or run for others must offer their source code under the AGPL; a commercial license without these obligations is available via teufel-it.de. namarr is not affiliated with TMDB, TheTVDB, TVmaze or AniDB. This product uses the TMDB API but is not endorsed or certified by TMDB.