Managing Your Library
Configure library scanning, folder and file naming conventions, and manage series metadata.
Library Directory
Set your root comic library path with DESTINATION_DIR. Comicarr creates series subfolders here based on your folder format. You can also configure multiple destination directories with MULTIPLE_DEST_DIRS.
Related settings:
| Setting | Default | Description |
|---|---|---|
CREATE_FOLDERS | True | Automatically create series folders when adding. |
DELETE_REMOVE_DIR | False | Remove the folder when deleting a series. |
MAINTAINSERIESFOLDER | False | Keep folder structure even for paused series. |
Folder Format
The FOLDER_FORMAT setting controls how series directories are named. Default: $Series ($Year).
Available Tokens
| Token | Description | Example |
|---|---|---|
$Series | Series name | Batman |
$Year | Start year | 2016 |
$Publisher | Publisher name | DC Comics |
$Imprint | Imprint name | Vertigo |
$Type | Series type | Annual, One-Shot |
$Annual | Annual indicator | Annual |
Example: $Publisher/$Series ($Year) produces DC Comics/Batman (2016)/.
File Format
The FILE_FORMAT setting controls how individual issue files are renamed. Default: $Series $Annual $Issue ($Year).
Available Tokens
| Token | Description | Example |
|---|---|---|
$Series | Series name | Batman |
$Issue | Issue number | 001 |
$Year | Issue year | 2016 |
$Annual | Annual indicator (if applicable) | Annual |
$Monthly | Month indicator | 01 |
Example: $Series $Issue ($Year) produces Batman 001 (2016).cbz.
Naming Options
REPLACE_SPACES (default: False) -- replace spaces in filenames with a character.
REPLACE_CHAR (default: .) -- the character to use when replacing spaces.
With both enabled: Batman 001 (2016) becomes Batman.001.(2016).
ZERO_LEVEL (default: False) -- pad issue numbers with leading zeros.
ZERO_LEVEL_N (default: none) -- padding level. Options: none, 0x (2-digit), 00x (3-digit).
With ZERO_LEVEL enabled and ZERO_LEVEL_N set to 00x: issue 5 becomes 005.
LOWERCASE_FILENAMES (default: False) -- convert all filenames to lowercase.
When enabled: Batman 001 (2016).cbz becomes batman 001 (2016).cbz.
Library Scanning
Comicarr scans your library to match files on disk to known series and issues. A scan runs:
- Automatically when series metadata changes (if
SCAN_ON_SERIES_CHANGESis enabled) - Manually from Manage > Force Library Scan
Verbose logging during scans can be toggled with FOLDER_SCAN_LOG_VERBOSE.
Cover Management
Comicarr downloads cover images from ComicVine for display in the UI.
COMIC_COVER_LOCAL-- store cover images alongside comic files.COVER_FOLDER_LOCAL-- store covers in a dedicated folder within the series directory.ALTERNATE_LATEST_SERIES_COVERS-- use the latest issue cover as the series thumbnail.
To regenerate covers after a metadata refresh, use the Regenerate Covers option on the series detail page.
Series JSON Listings
Comicarr can write a series.json file into each series folder containing structured metadata.
SERIES_METADATA_LOCAL(default:False) -- enable writing series JSON files.SERIESJSON_FILE_PRIORITY(default:False) -- prefer the local JSON file over ComicVine data when both exist.
This is useful for external tools or media servers that read metadata from the filesystem.
Enable ADD_TO_CSV to maintain a CSV log of all series additions, useful for backup and migration purposes.