[Feature Request] Update documentation for importing TV shows

[honeypotfields]

Edit: see comment for feature request. Bug report left in for context.

Describe the bug
When importing a TV show, MediaManager creates blank season folders with no episodes inside, even if everything is named as the sparse documentation on this suggests. Apparently it cannot find them (see media_manager.log).

To Reproduce

1. Rename an existing TV show and all its episodes (i.e. with KRenamer or Bulk Rename Utility), removing all extra files like thumb.jpg in case they cause conflict somehow
   • "ShowName (Year) [tmdbid-xxx]"
     • Season 1
       • S1E1
       • S1E2
       • etc
     • Season 2
       • S2E1
       • S2E2
       • etc
     • etc
2. Reload MM web UI in browser and wait for it to detect new show "ShowName (Year) [tmdbid-xxx]"
3. Import the show and check for empty Season folders with a file manager like Dolphin or FileBrowser Quantum

Expected behavior
The episode files such as S1E1, S2E1, etc. are copied over to the new Season folders.

media_manager.log

{"timestamp": "2026-01-12T20:18:11.829Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.841Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.841Z", "level": "WARNING", "module": "media_manager.notification.manager", "message": "No notification providers configured"}
{"timestamp": "2026-01-12T20:18:11.845Z", "level": "WARNING", "module": "media_manager.tv", "message": "S1E1 not found when trying to import episode for show MyShow."}
{"timestamp": "2026-01-12T20:18:11.856Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.856Z", "level": "WARNING", "module": "media_manager.notification.manager", "message": "No notification providers configured"}
{"timestamp": "2026-01-12T20:18:11.860Z", "level": "WARNING", "module": "media_manager.tv", "message": "S1E2 not found when trying to import episode for show MyShow."}
{"timestamp": "2026-01-12T20:18:11.869Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.869Z", "level": "WARNING", "module": "media_manager.notification.manager", "message": "No notification providers configured"}
{"timestamp": "2026-01-12T20:18:11.873Z", "level": "WARNING", "module": "media_manager.tv", "message": "S1E3 not found when trying to import episode for show MyShow."}
{"timestamp": "2026-01-12T20:18:11.889Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.890Z", "level": "WARNING", "module": "media_manager.notification.manager", "message": "No notification providers configured"}
{"timestamp": "2026-01-12T20:18:11.894Z", "level": "WARNING", "module": "media_manager.tv", "message": "S1E4 not found when trying to import episode for show MyShow."}
{"timestamp": "2026-01-12T20:18:11.904Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.904Z", "level": "WARNING", "module": "media_manager.notification.manager", "message": "No notification providers configured"}
{"timestamp": "2026-01-12T20:18:11.908Z", "level": "WARNING", "module": "media_manager.tv", "message": "S1E5 not found when trying to import episode for show MyShow."}
{"timestamp": "2026-01-12T20:18:11.916Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.917Z", "level": "WARNING", "module": "media_manager.notification.manager", "message": "No notification providers configured"}
{"timestamp": "2026-01-12T20:18:11.925Z", "level": "WARNING", "module": "media_manager.tv", "message": "S1E6 not found when trying to import episode for show MyShow."}
{"timestamp": "2026-01-12T20:18:11.933Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.933Z", "level": "WARNING", "module": "media_manager.notification.manager", "message": "No notification providers configured"}
{"timestamp": "2026-01-12T20:18:11.937Z", "level": "WARNING", "module": "media_manager.tv", "message": "S1E7 not found when trying to import episode for show MyShow."}
{"timestamp": "2026-01-12T20:18:11.945Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.945Z", "level": "WARNING", "module": "media_manager.notification.manager", "message": "No notification providers configured"}
{"timestamp": "2026-01-12T20:18:11.949Z", "level": "WARNING", "module": "media_manager.tv", "message": "S1E8 not found when trying to import episode for show MyShow."}
{"timestamp": "2026-01-12T20:18:11.957Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.957Z", "level": "WARNING", "module": "media_manager.notification.manager", "message": "No notification providers configured"}
{"timestamp": "2026-01-12T20:18:11.961Z", "level": "WARNING", "module": "media_manager.tv", "message": "S1E9 not found when trying to import episode for show MyShow."}
{"timestamp": "2026-01-12T20:18:11.969Z", "level": "WARNING", "module": "media_manager.tv", "message": "Library  not defined in config, using default TV directory."}
{"timestamp": "2026-01-12T20:18:11.969Z", "level": "WARNING", "module": "media_manager.notification.manager", "message": "No notification providers configured"}
{"timestamp": "2026-01-12T20:18:11.973Z", "level": "WARNING", "module": "media_manager.tv", "message": "S1E10 not found when trying to import episode for show MyShow."}

Version
Latest

Additional context
My existing movies (i.e. folder "MovieName", file inside "Movie.mkv") all import successfully even without bothering to rename; the movie is copied over to the new MM folder. Not renaming shows and leaving them with human-friendly names like folder "ShowName" and "1. EpisodeName" results in detection failure (so I tried again with naming them properly which also failed). I do not have every single episode for the show I tested. Season 0 is missing entirely and there are extra webisodes that MM doesn't understand. A big reason why I want to use MM in the first place is to fill out my incomplete collections with a nice UI.

docker-compose.yaml

services:
  mediamanager:
    container_name: mmserver
    image: ghcr.io/maxdorninger/mediamanager/mediamanager:latest
    restart: no
    user: 1000:1000
    ports:
      - 8000:8000
    environment:
      - CONFIG_DIR=/toml
    volumes:
      - ./:/toml
      - ${MEDIA}:/data/
      - ./configMM:/app/config/
      - ./images:/images/
    depends_on:
      db:
        condition: service_healthy
      prowlarr:
        condition: service_started
      qbittorrent:
        condition: service_started

  db:
    container_name: mmpostgres
    image: postgres:17
    restart: no
    user: 1000:1000
    volumes:
      - ./postgres:/var/lib/postgresql/data
    healthcheck:
      test:
        - CMD-SHELL
        - pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}
      interval: 10s
      timeout: 5s
      retries: 5
    environment:
      POSTGRES_USER: MediaManager
      POSTGRES_DB: MediaManager
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

  prowlarr:
    image: lscr.io/linuxserver/prowlarr:latest
    container_name: prowlarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=${TZ}
    volumes:
      - ./configPR:/config
    ports:
      - 9696:9696
    restart: unless-stopped
    depends_on:
      flaresolverr:
        condition: service_healthy

  flaresolverr:
    image: ghcr.io/flaresolverr/flaresolverr:latest
    container_name: flaresolverr-prowlarr
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
      - LOG_HTML=false
      - CAPTCHA_SOLVER=none
      - TZ=${TZ}
    healthcheck:
      test:
        - CMD
        - curl
        - -f
        - http://127.0.0.1:8191/health
      interval: 30s
      timeout: 10s
      start_period: 30s
      retries: 3
      
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent-prowlarr
    network_mode: host #to bind network interface to host VPN in qBittorrent web UI advanced settings
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=${TZ}
      - WEBUI_PORT=8080
      - TORRENTING_PORT=6881
    volumes:
      - ${QB_CONFIG}:/config
      - ${DOWNLOADS}:/downloads
      - ${MEDIA}/z_Processing:/ingest #completed downloads get moved here
    restart: unless-stopped

modified sections of config.toml

[misc]
# it's very likely that you need to change this for MediaManager to work
frontend_url = "http://myserverip:8000" # note the lack of a trailing slash
cors_urls = ["http://myserverip:8000"] # note the lack of a trailing slash

image_directory = "/images"
tv_directory = "/data/TV"
movie_directory = "/data/Movies"
torrent_directory = "/data/z_Processing"

[database]
host = "db"
port = 5432
user = "MediaManager"
password = "64randomLeTTersandnumbers"
dbname = "MediaManager"

[auth]
email_password_resets = false # if true, you also need to set up SMTP (notifications.smtp_config)

token_secret = "different64randomLeTTersandnumbers" # generate a random string with "openssl rand -hex 32", e.g. here https://www.cryptool.org/en/cto/openssl/
session_lifetime = 86400  # this is how long you will be logged in after loggin in, in seconds

admin_emails = ["admin@example.com", "me@myemail.me"]

[torrents]
# qBittorrent settings
[torrents.qbittorrent]
enabled = true
host = "http://myserverip"
port = 8080
username = "admin"
password = "another64randomLeTTersandnumbers"

[indexers]
# Prowlarr settings
[indexers.prowlarr]
enabled = true
url = "http://myserverip:9696"
api_key = "32randomlettersandnumbers"
timeout_seconds = 60

# its very unlikely that you need to change this
[metadata]
[metadata.tmdb]
tmdb_relay_url = "https://metadata-relay.dorninger.co/tmdb"
#primary_languages = [""] #commented out to prevent pydantic startup crash
#default_language = "en" #commented out to prevent pydantic startup crash

• I understand, that without logs and/or screenshots and a detailed description of the problem, it is very hard to fix bugs.
• I have checked the documentation for help.
• I have searched the issues for similar issues and found none.

[honeypotfields]

I figured it out by downloading a season of a show from MM:
ShowName SXXEXX -resolutionP EpisodeName.ext, where XX has a leading zero if single digit but not if double digit

I also tested 6 variations of this with a MM foldername "ShowName (Year) [tmdbid-XXX]" by batch renaming episodes of an existing show with KRename to see how much I could reduce before importing broke.

• Season 1: S0XE0X -1080P EpisodeName.mkv; S0XE0X -1080P EpisodeName.jpg
• Season 2: ShowName S0XE0X -1080P EpisodeName.mkv; ShowName S0XE0X -1080P EpisodeName.mkv.jpg
• Season 3: S0XE0X - 1080P.mkv; S0XE0X - 1080P.jpg
• Season 4: S0XE0X -1080P EpisodeName.mkv; no jpgs
• Season 5: ShowName S0XE0X -1080P EpisodeName.mkv; no jpgs
• Season 6: S0XE0X - 1080P.mkv; no jpgs

And another 2 tests with a lazy foldername (if it works for movies why not TV shows?) and episode names.

• "ShowName S0XE0X"
• "ShowName S0XE0X - IMPORTED"

Results: No images were copied over. All EpisodeNames were removed. No episodes without ShowName were detected. An import of an import did not change the filename.
Finally I tested renaming all episodes from Season 1 according to both the above working patterns, "ShowName S0XE0X" and "ShowName S0XE0X - IMPORTED", sideloading them into the empty Season 1 folder while MM was running, and reloading the web UI in browser. Not detected.

Takeaway: So the optimal way to name TV shows is "ShowName" for the main folder, "Season X" for season folders, and "ShowName SXXEXX" for episodes, where XX has a leading zero if single digit but not if double digit (I have no idea how it handles triple digits and beyond). Any human-readable episode titles or Jellyfin thumbnails must be restored manually. It is ideal to import each TV show folder one time to avoid having to reimport the whole thing to update one season downloaded outside of MM. Importing previously imported episodes will not change their names though.

An update to the documentation for importing existing media that explicitly spells out the takeaway points would be very helpful. If Reddit is any indication, many first-time MM users will simply fall back to their working arr stack if they meet unexpected roadblocks like not being able to easily import their TV shows, especially without something like a Discord server where they can easily ask the "stupid questions". Often these are answerable by a single sentence like "You have no indexers in your toml" or "You need to comment out these two lines" and the root cause of many other symptoms.