LibrarianMedia hygiene and enrichment for self-hosted libraries

Install with Docker Compose

Librarian listens on port 3000. The example binds it to loopback on 3002 and shares the same ./library mount that Jellyfin and Tide use:

services:
  librarian:
    image: getcoral/librarian:latest
    restart: unless-stopped
    user: "${PUID}:${PGID}"
    depends_on: [jellyfin]
    ports:
      - "127.0.0.1:3002:3000"
    environment:
      LIBRARIAN_DATA_DIR: /data
      JELLYFIN_URL: http://jellyfin:8096
      JELLYFIN_API_KEY: ${JELLYFIN_API_KEY}
      JELLYFIN_USER_ID: ${JELLYFIN_USER_ID}
      # Seeds the roots. They arrive switched off — turn them on in the UI.
      LIBRARIAN_DOWNLOADS_DIR: /library/downloads/complete
      LIBRARIAN_MEDIA_DIR: /library/media/movies
    volumes:
      - ./librarian-data:/data
      # The same single mount, at the same path, as Jellyfin and Tide.
      - ./library:/library
    networks: [coral]

user: "${PUID}:${PGID}" matters. Librarian never chowns anything, so it has to run as a user that can already read and write the files it is moving — the same one Jellyfin and Tide run as. Find yours with id -u and id -g.

Open Librarian at http://localhost:3002 on first run. The roots you seeded through environment variables will be listed but disabled, and you enable each one by hand. That is deliberate: mounting a directory into a container is not the same as granting permission to reorganise it.

One mount, not one per directory

This is the single rule that determines whether Librarian is fast or slow, and it is worth understanding before you write your Compose file.

Librarian imports finished downloads by hardlinking them into your media tree. A hardlink is a second name for the same bytes on disk, so importing a 40 GB remux is instantaneous and costs no extra space, and the torrent keeps seeding from the original path.

A hardlink cannot cross a filesystem. Less obviously, it cannot cross a mount point either — even when both sides are the same physical filesystem. So this does not work:

    volumes:
      - ./downloads:/downloads    # separate mount
      - ./media:/media            # separate mount — links across these will fail

And this does:

    volumes:
      - ./library:/library        # one mount containing downloads/ and media/

Nothing that inspects statSync().dev can predict this correctly, which is why Librarian decides by attempting the link rather than comparing device IDs. If the attempt fails, nothing breaks — the import becomes a verified copy. Correct, just slower and twice the space.

What Librarian actually does

Import is the front half. Librarian watches the roots you enable, recognises finished downloads, and moves them into your media tree under names Jellyfin will parse cleanly.

The back half is hygiene on what is already there. It surfaces the things that quietly degrade a large library over time: titles with missing or thin metadata, weak or absent posters, and duplicates that accumulated from re-downloads and re-encodes. Bulk renaming, tagging and enrichment operations are queued rather than applied one file at a time.

Throughout, Jellyfin stays the source of truth. Librarian does not maintain a parallel metadata database or a second idea of what your library contains — it reads Jellyfin, changes files on disk, and asks Jellyfin to rescan.

Where Librarian sits next to the *arr stack

If you already run Radarr and Sonarr, Librarian is not a replacement and installing it does not mean tearing anything out. Those tools solve acquisition: watch for a release, search indexers, hand it to a download client. Librarian starts one step later, when files exist and the question becomes whether the library is actually in good shape.

If you do not run the *arr stack — because you acquire media by hand and only want the organising and cleanup half — then Librarian covers that half on its own, paired with Tide for the downloads themselves.

The comparison against a dedicated metadata tool is in Librarian vs tinyMediaManager.