Libraries
Libraries are root directories where Luminarr tracks your movie files. Each library maps a folder on disk to a default quality profile, and is the target for all imports.
What is a Library?
A library is a directory on disk — such as /data/movies — that Luminarr monitors and manages.
When a download completes, Luminarr imports the file into one of your libraries by either moving
or hardlinking it into the correct folder. The library also determines the naming convention
applied to imported files.
You can have multiple libraries — for example, one for 4K content and one for 1080p — each with its own quality profile and naming rules. Movies are associated with exactly one library at a time.
Root directory
The top-level folder that contains all movies managed by this library. Luminarr will create per-movie subfolders inside it.
Default quality profile
New movies added to this library inherit this profile. You can override the profile on individual movies at any time.
Import mode
Choose between move (transfer the file) or hardlink (keep the original for seeding). Hardlink requires the source and destination to be on the same filesystem.
Min free space
Luminarr will refuse to import if the library drive has less than this amount of free space remaining. Prevents disk-full failures.
Configuration Fields
| Field | Description | Default |
|---|---|---|
| Root Path | Absolute path to the root directory on disk. Must already exist and be writable by the Luminarr process. | — |
| Default Quality Profile | Quality profile assigned to newly added movies. Does not retroactively change existing movies. | First available profile |
| Min Free Space | Minimum disk space (in GB) that must remain after an import. Set to 0 to disable the check. | 0 GB |
| Naming Format | Token template for the imported filename, e.g. {Movie Title} ({Year}) [{Quality}]. |
Standard |
| Folder Format | Token template for the per-movie subfolder created inside the root path, e.g. {Movie Title} ({Year}). |
Standard |
| Tags | Optional labels that link this library to specific indexers, download clients, or import lists. See Tags. | None |
Naming tokens
Use these tokens in both Naming Format and Folder Format fields:
| Token | Example output |
|---|---|
{Movie Title} | The Dark Knight |
{Movie CleanTitle} | The Dark Knight |
{Year} | 2008 |
{ImdbId} | tt0468569 |
{TmdbId} | 155 |
{Quality} | Bluray-1080p |
{Resolution} | 1080p |
{Source} | Bluray |
{Codec} | x265 |
{Edition} | Director's Cut |
Running in Docker
Use container-side paths. The Root Path you enter in Luminarr must be the path
inside the container, not your host path. If you mount /host/movies to
/data/movies in your compose file, set the library Root Path to /data/movies.
A typical Docker Compose volume mapping looks like this:
volumes: - /your/movies:/data/movies # host path : container path - /your/config:/config # Luminarr database and settings - /your/downloads:/downloads # download client output
With this mapping, enter /data/movies as the library Root Path in Luminarr.
If your download client also runs in Docker, its completed downloads path must resolve to the same
underlying filesystem location so hardlinks work correctly.
Hardlinks require a shared filesystem. For hardlinks to work between your download client and Luminarr, both containers must mount the same root volume — not separate mounts pointing to the same host directory.
Key Operations
Scan library
A library scan walks the root directory and reconciles what Luminarr finds on disk with its database. New files are matched against monitored movies; missing files update the movie status to unmonitored. Scans run automatically every 6 hours but can be triggered manually from System → Tasks.
Change root path
If you move your movie folder to a new location, update the Root Path in the library settings. Luminarr will re-resolve all movie file paths relative to the new root on the next scan. The files themselves are not moved — you must move them manually first.
Delete a library
Deleting a library removes it from Luminarr's configuration. Movies previously associated with the library remain in the database (their files are not deleted from disk) but become unassigned and will need to be reassigned to another library.
Multiple libraries are additive. All libraries are searched together when checking for missing movies or running RSS sync. There is no per-library isolation — quality upgrades can pull from any enabled indexer regardless of which library the movie belongs to.