Lifecycle Rules

The lifecycle rule engine lets you define conditions to automatically identify and act on media in your library. It uses a flexible rule group structure with AND/OR logic.

Concepts

Rule Sets

A rule set is a named collection of rules and actions. Each rule set targets a specific media type (movies, series, or music).

Rule Groups

Rules are organized into groups. Each condition (and each nested sub-group) connects to the one above it with AND or OR:

• AND: must match together with everything above it
• OR: matches if either side does

When a group uses a single connector throughout, this reads exactly as you'd expect — all conditions must match (AND) or any condition may match (OR). When AND and OR are mixed, conditions combine top to bottom, each connector applying to the combined result of everything above it — so A OR B AND C means (A OR B) AND C. The builder shows a hint whenever this applies, and the Logic Preview panel beside the builder always spells out the exact grouping with parentheses (hovering a condition highlights its line in the preview).

Groups can be nested to make grouping explicit — a sub-group is evaluated on its own first, then joins its parent as a single result.

Rules

Each individual rule consists of:

1. Field — what property to evaluate (e.g., playCount, resolution, addedAt)
2. Operator — how to compare (e.g., equals, greaterThan, before)
3. Value — the target value

Negation is part of the operator choice: alongside each comparison the picker offers its inverse — Not Equals, Not Contains, Not Greater Than, Not Between, and so on.

Whole groups can be negated too. Every group has a NOT toggle that inverts its entire result — for example NOT (watched by Alice OR watched by Bob) matches items watched by neither. The Logic Preview shows the negation in place, and items the group would have matched are excluded instead. (Stream query groups negate through their ANY/NO quantifier rather than a NOT toggle.)

Available Fields

Over 50 fields are available for rule conditions.

Media Fields

Field	Description	Operators
playCount	Number of times played	equals, greaterThan, lessThan, etc.
watchedByUser	Server username that played the item (Plex/Jellyfin/Emby) — multi-select	equals, notEquals, contains, notContains
lastPlayedAt	When last played	before, after, inLastDays
addedAt	When added to library	before, after, inLastDays
title	Media title	equals, contains, matchesWildcard
parentTitle	Series name (for episodes)	equals, contains, matchesWildcard
year	Release year	equals, greaterThan, lessThan, etc.
contentRating	Content rating (PG, R, etc.)	equals, notEquals
rating	Critic rating	greaterThan, lessThan, etc.
audienceRating	Audience rating	greaterThan, lessThan, etc.
studio	Production studio	equals, contains
genre	Genre(s)	equals, contains
duration	Duration in minutes	greaterThan, lessThan, etc.

Video Fields

Field	Description
resolution	4K, 1080P, 720P, etc.
videoCodec	H.264, H.265, AV1, etc.
videoBitrate	Video bitrate
videoBitDepth	8-bit, 10-bit
videoProfile	Baseline, Main, High
videoFrameRate	Frame rate (23.976, 24, etc.)
aspectRatio	16:9, 4:3, 2.39:1, etc.
dynamicRange	SDR, HDR10, HDR10+, Dolby Vision, HLG
scanType	progressive, interlaced

Audio Fields

Field	Description
audioCodec	AAC, AC3, FLAC, etc.
audioChannels	Channel count (2, 6, 8, etc.)
audioProfile	Dolby Atmos, DTS-HD MA, etc.
audioSamplingRate	Sampling rate (48000, etc.)
audioBitrate	Audio bitrate
audioLanguage	Audio track language
audioStreamCount	Number of audio tracks

File Fields

Field	Description
fileSize	File size (in MB)
container	File container (MKV, MP4, etc.)
subtitleLanguage	Subtitle track language
subtitleStreamCount	Number of subtitle tracks

External / *arr Fields

These fields require configured Sonarr, Radarr, or Lidarr integrations.

Field	Description
foundInArr	Whether the item exists in the linked *arr instance
arrMonitored	Whether monitored in *arr
arrTag	Tags in *arr instance
arrQualityProfile	Quality profile name
arrQualityName	Name of the current file's quality (Radarr / movies only)
arrQualityCutoffMet	Whether the current file meets the quality profile's cutoff (Radarr / movies only). true once the file is at or above the cutoff, so no upgrade is pending
arrCustomFormatScore	Custom format score of the movie's current file (Radarr / movies only)
arrStatus	Release/lifecycle status in *arr (e.g. released, continuing)
arrEnded	Whether the series has ended (Sonarr / series only)
arrSeriesType	Series type: standard, daily, or anime (Sonarr / series only)
arrRating	Rating in *arr. For movies this is the IMDB rating; for series/music it is the single aggregate rating the *arr exposes
arrTmdbRating	TMDB rating in *arr (Radarr / movies only — Sonarr/Lidarr expose only a single flat rating)
arrRtCriticRating	Rotten Tomatoes critic rating in *arr (Radarr / movies only — Sonarr/Lidarr expose only a single flat rating)
arrOriginalLanguage	Original language in *arr (not music)
arrRuntime	Runtime in minutes (Radarr / movies only)
arrSizeOnDisk	Size on disk in MB
arrPath	File path in *arr
arrReleaseDate	Digital/physical release date (Radarr / movies only)
arrInCinemasDate	In-cinemas date (Radarr / movies only)
arrFirstAired	First-aired date (Sonarr / series only)
arrDateAdded	When the item was added to *arr
arrDownloadDate	When the current file was downloaded (Radarr / movies only)
arrSeasonCount	Total season count (Sonarr / series only)
arrEpisodeCount	Total episode count (Sonarr / series only)
arrHasUnaired	Whether the series has unaired episodes (Sonarr / series only)
arrMonitoredSeasonCount	Number of monitored seasons (Sonarr / series only)
arrMonitoredEpisodeCount	Number of monitored episodes (Sonarr / series only)

Missing *arr data is fail-closed

If an item isn't in the linked *arr instance, or a specific field has no value (for example a movie with no downloaded file has no quality name, quality-cutoff, or size), no comparison operator matches it — including negative operators like Not Equals / Not Contains and the NOT toggle. This is deliberate so lifecycle rules never delete an item on the strength of absent *arr data. To target items with missing data, use the Is Empty (isNull) operator, or the foundInArr field.

Seerr Fields

These fields require a configured Seerr integration.

Field	Description
seerrRequested	Whether requested in Seerr
seerrRequestDate	When the request was made
seerrRequestCount	Number of requests
seerrRequestedBy	Who requested it
seerrApprovalDate	When approved
seerrDeclineDate	When declined

Operators

Operator	Applicable Types	Description
equals	text, number	Exact match
notEquals	text, number	Not an exact match
greaterThan	number	Greater than value
greaterThanOrEqual	number	Greater than or equal
lessThan	number	Less than value
lessThanOrEqual	number	Less than or equal
contains	text	For free-text fields (e.g. title, path): substring match (case-insensitive). For enumerable fields (e.g. quality profile, tag, codec) the operator presents a multi-select and matches if the item's value equals any selected value (list membership, not substring).
notContains	text	Inverse of contains — same free-text vs enumerable distinction.
matchesWildcard	text	Wildcard match (* = any characters, ? = single character)
notMatchesWildcard	text	Does not match wildcard pattern
before	date	Before a specific date
after	date	After a specific date
inLastDays	date	Within the last N days

Building Rules

Using the Rule Builder

1. Create a Rule Set: Give it a name and select the target media type
2. Add rules: Select a field, operator, and value
3. Group rules: Use AND/OR groups to combine conditions
4. Nest groups: Create sub-groups for complex logic
5. Toggle rules: Enable/disable individual rules or groups without deleting them
6. Negate: Pick a "Not …" operator to invert a condition, or flip a group's NOT toggle to invert the whole group
7. Reorder: Drag rules to change their position within a group

Example: Identify Old, Unwatched Movies

Create a rule set with an AND group containing:

• playCount equals 0 — Never watched
• addedAt before 2023-01-01 — Added over a year ago
• resolution notEquals 4K — Not 4K quality

Example: Find Duplicate Quality

Create a rule set with an OR group:

• resolution equals 480P
• resolution equals SD
• videoCodec equals mpeg2video

Example: Watched Only By Departed Household Members

Create a rule set with an AND group:

• watchedByUser contains alice|bob — Only watched by people no longer in the household
• watchedByUser notContains carol|dave — Never watched by current household members
• addedAt notInLastDays 180 — Been in the library for at least 6 months

The watchedByUser field reads from the per-user play history synced from Plex / Jellyfin / Emby. "Watched by" means any play by that user, regardless of how much of the item they actually consumed. The dropdown is populated with usernames the sync has seen on your connected servers.

Converting a Query into a Rule Set

The Query Builder at /library/query shares its rule shape with the lifecycle engine. If you build a query that you'd like to enforce on a schedule, use Convert to Lifecycle Rule on the query builder toolbar to create a rule set without re-entering the criteria.

What the conversion does:

• Copies the rule tree verbatim — no changes to fields, operators, or values.
• Prompts you to pick a target library type when the query targets more than one (rule sets are scoped to a single type).
• Drops any rules that don't apply to the chosen library type and shows you the list before submitting. For example, when targeting Movies, any series-aggregate or music-only rules are removed.
• Creates the new rule set with actionEnabled off and no action configured — matches will be detected on the next scheduler run, but nothing is deleted or unmonitored until you choose an action.

After conversion, you're redirected to the new rule set's editor so you can pick an action type, set the delay, configure tags, and re-evaluate.

Unsaved query drafts

While you build a query, it's automatically kept for the current browser tab, so if you navigate away and come back the in-progress query is still there — no need to rebuild it. This is separate from Save (which stores a named query in the database): the draft lives only in your browser, isn't shared between tabs, and is cleared when you close the tab. When a draft is restored you'll see a short notice with Discard (start fresh) and a dismiss option. Use New at any time to clear the builder and the draft.

Running Actions Directly from the Query Page

For one-off cleanups you don't want to schedule, you can run a lifecycle action on query results without creating a rule set:

1. Pick the Arr instance(s) for the media types you want to act on in the query toolbar (Radarr for movies, Sonarr for series, Lidarr for music).
2. Run the query, then tick the checkbox on each result you want to act on (in table or card view). A select-all checkbox is available in the table header, and a Select all / Deselect all toggle sits above the results in card view. While a query runs, a progress bar above the results tracks each phase (resolving servers, fetching *arr/Seerr metadata, querying the library, evaluating rules) instead of a bare spinner.
3. In the Actions bar above the results — always visible but disabled until you select at least one item — choose an action (e.g. Delete from Radarr, Unmonitor & Delete Files, Change Quality Profile), set any action-specific options (the target quality profile and Search for upgrade for a profile change, import exclusion / Search after for deletions), optionally add/remove Arr tags, then Run action and confirm. While the action runs, a progress bar below the Actions bar tracks its phases — validating the selection, then running the action item-by-item — and the bar fills as each item completes. The validating phase narrates what it's doing on its sub-line (re-running your query to confirm the selection still matches, resolving series episodes, checking the exception list, then loading the items), forwarding the re-query's own progress so a slow re-check on a large library isn't opaque. A sub-line shows the live per-item count (e.g. 3 / 12) alongside the item currently being processed and the step in flight, so multi-step actions are visible: tag changes are applied first, then the main action (a quality-profile change, deletion, etc.), and the follow-up search when Search after is enabled. A large batch shows real progress instead of a bare spinner.

The result count line above the results also reports the total file size of all results, so you can see how much disk a query covers at a glance. Once you select items, the Actions bar shows the combined size of the current selection next to the selected count — handy for gauging how much space a cleanup will reclaim before you run it.

Notes:

• Runs immediately — there is no delay, unlike scheduled rule actions.
• One Arr family per run — an action applies only to selected results of its media type (e.g. Delete from Radarr acts on selected movies); selected items of other types are skipped and reported in the result toast.
• Before acting, the query is re-run so only items that still match are affected, and items on the Lifecycle Exceptions list are skipped automatically.
• Every run is recorded in the Actions history (and deletion stats) labelled Ad-hoc query action, so there's a full audit trail even though no rule set exists.

Previewing Matches

Before executing any actions, use the Preview feature to see which media items match your rules:

• Shows a count of matching items
• Displays a paginated list (50 per page) with metadata
• Updates in real time as you modify rules
• Shows a live progress bar through each phase (fetching *arr/Seerr metadata, evaluating rules, computing matched criteria) so large libraries don't just spin

Actions

Actions determine what happens to matched media. Configure them in the Actions tab of a rule set.

Available Actions

Action	Description	Requires
Delete	Remove from *arr and optionally delete files	Sonarr/Radarr/Lidarr
Unmonitor	Stop monitoring for upgrades in *arr	Sonarr/Radarr/Lidarr
Change Quality Profile	Switch the *arr item to a different quality profile	Sonarr/Radarr/Lidarr
Search for New Copy	Trigger an *arr search for a new copy of the item	Sonarr/Radarr/Lidarr
Do Nothing	Track matches without taking action	—

Tags can be added or removed as a supplementary operation alongside any action (including Do Nothing).

Change Quality Profile

This action switches a movie, series, or artist to a different quality profile in the linked *arr instance.

• The dropdown is populated live from the selected *arr instance's quality profiles, so it always reflects what the *arr server currently offers.
• Items that are already on the selected profile are skipped at execution time. No update call is made and the action completes as a no-op.
• Combining this action with arrQualityProfile rule conditions lets you upgrade or downgrade items that don't match your desired profile (for example: "any movie whose current quality profile is SD → switch to HD-1080p").
• The target profile is required when the action is enabled — Save is disabled until one is selected.
• Toggle Search for upgrade after profile change to trigger an immediate *arr search after the profile is updated. The search only fires when the profile actually changed — skipped (no-op) items don't trigger a search.

Search for New Copy

This action triggers an *arr search for a new copy of the matched movie, series, or artist without changing monitoring, quality profile, or deleting anything. It is a standalone alternative to the Search after / Search for upgrade toggles that accompany the delete-files and quality-profile actions — use it when all you want is to kick off a fresh search.

Configuring Actions

Each action links a rule set to an *arr instance:

1. Select the *arr integration (e.g., "My Radarr")
2. Choose the action type (delete, unmonitor, do nothing)
3. Set action-specific options (e.g., delete files toggle)
4. Optionally configure tags to add or remove
5. Set priority — actions execute top-to-bottom

Caution

The Delete action permanently removes files from your *arr instance and, optionally, from disk. Preview your matches carefully before enabling deletion rules.

Note

Repeat scheduling. A non-destructive action (Unmonitor, Do Nothing, Search for New Copy, Change Quality Profile) leaves the item in your library, so it keeps matching the rule. To avoid re-running the same action every cycle, Librariarr won't re-schedule an item that already has a completed action with an identical configuration. The comparison covers the whole action — its type, target quality profile, Arr instance, search-after toggle, and tag set — so you can re-configure a rule's action without recreating the rule and it will fire again. For example, changing the action from Search for New Copy to Delete from Radarr, editing the tags an action applies, or pointing a Change Quality Profile action at a different profile all schedule the action again, because the new action has never run on that item. Completed Delete actions are always eligible to re-schedule, so a deleted title that is re-downloaded (or whose delete failed silently) is acted on again.

Tip

See Deletion Safety for an in-depth, layer-by-layer description of every check that stands between a rule firing and a file being deleted, including the exact source locations and tests that enforce each one.

Recycle Bin Safety Check

When you configure a destructive action (Delete, Delete Files, Unmonitor & Delete Files, Monitor & Delete Files) for an *arr instance, Librariarr queries that instance for its Recycle Bin Path (Settings → Media Management in Sonarr/Radarr/Lidarr).

• If a recycle bin path is set, deleted files are sent to that path before being permanently removed (per the configured cleanup days).
• If no path is set, deletes are immediate and unrecoverable.

When the recycle bin is disabled, Librariarr surfaces the risk in two places:

1. An inline amber warning appears under the Action type select.
2. On save, a confirmation modal blocks the save until you check "I understand that deletes will be permanent and unrecoverable." The modal includes a deep link to the *arr instance's Media Management settings so you can configure a recycle bin without leaving the page.

The acknowledgement is remembered per *arr instance for the current session — once you accept, you won't be re-prompted for that same instance until the page is reloaded.

Plex Collections

A rule set can keep a Plex collection in sync with its matches — useful for surfacing a "Leaving Soon" shelf to your users. In the rule editor, turn on Sync matches to a Plex collection, then pick a collection from the dropdown or choose Create new collection….

Collections are reusable, saved definitions (Plex only). Each one owns its presentation settings:

• Collection name — the title shown in Plex.
• Sort name (optional) — a sort title prefix (e.g., !001) to pin the collection to the top of a library.
• Sort order — Alphabetical, Release date, or Action date.
• Display on home screens / Display in library recommended — Plex visibility toggles.

Because the settings live on the collection (not the rule), editing them from any rule applies to every rule synced to that collection.

Merging rules into one collection

Multiple rule sets can target the same collection. When they do, the collection's membership is the union of all of their matches — Librariarr never lets two rules fight over the same collection. For example, separate "4K movies leaving soon" and "unwatched series leaving soon" rules can both feed a single Leaving Soon shelf (within the same library type).

A collection is scoped to one library type (Movies, Series, or Music), since a Plex collection lives inside a single library. To use the same name for both movies and series, create two collections.

Action-date ordering across rules

With Sort order: Action date, items are arranged soonest-scheduled-action first. When several rules feed the collection, the ordering pools the scheduled action dates of all of them, so the shelf is correctly interleaved regardless of which rule scheduled each item. (Items without a pending action are placed last.)

Lifecycle of a collection

• Disabling collection sync on a rule, or deleting the rule, simply detaches it — the collection is re-synced to the remaining rules' matches. The Plex collection is removed only when it has no remaining members.
• To delete a collection definition outright, select it in the dropdown and use the trash button. You can delete it from the last rule that uses it — doing so removes the collection from that rule and deletes it from Plex. The button is disabled (and the API refuses) only while other rules still reference it, so remove it from those first.

How Rules Are Evaluated

Rules are evaluated in two steps:

1. Step 1 — Local data: Rules based on your media's own properties (resolution, play count, dates, file size, etc.) are evaluated first using your database — this is fast.

2. Step 2 — External data: Rules based on Sonarr, Radarr, Lidarr, or Seerr data (tags, quality profiles, monitored status, requests) require live lookups to those services, so they run after Step 1 narrows down the results.

Note

Rules using external data (Step 2) are slower because they query your integrations. Use local-data rules to narrow your matches first for best performance.

Series scope and aggregate fields

For Series rule sets, the Series Scope toggle controls the unit of evaluation:

• Series scope on — the rule is evaluated against the whole show, and an action applies to the entire series. Every episode is a member of the match.
• Series scope off — the rule is evaluated against individual episodes, then results are grouped by show. A member-scoped action (such as Delete Files Only) acts only on the episodes that matched.

Some fields are series-aggregate fields — availableEpisodeCount, watchedEpisodeCount, watchedEpisodePercentage, lastEpisodeAiredAt, lastEpisodeAddedAt, and latestEpisodeViewDate. These describe the show as a whole and can only be computed across every episode, so a rule that references one is always evaluated at the series level — even with Series Scope off.

When Series Scope is off and your rule mixes an aggregate field with a per-episode field (for example, available episode count ≥ 20 and resolution = 4K), the show first has to qualify on the aggregate, and then a member-scoped file delete acts only on the episodes that individually satisfy the per-episode conditions (here, just the 4K episodes) — not every episode of the series. With Series Scope on, the same rule deletes the whole series.

Scheduling

Lifecycle processing runs on two independent schedules (configured in Settings → Scheduling):

• Detection: Evaluates rules and identifies matching media
• Execution: Performs configured actions on matched media

Both can be run manually via the Run Now button at any time.

Deletion Stats

The Pending Actions page displays a running total of data deleted by lifecycle actions — including the total bytes removed and the number of completed actions. This gives you visibility into how much storage the lifecycle system has reclaimed.

• Stats are computed from completed actions that have recorded file sizes
• Click the reset button to start counting from zero — historical action records are unaffected
• After a reset, only actions completed after the reset point are included in the totals

Limitations

• *arr actions require the corresponding integration to be configured and reachable
• Rules using integration data are slower and scale with the number of matches
• File size rules accept input in MB but are stored and compared in bytes
• Wildcard matching uses * (any characters) and ? (single character), not regex