General Settings
Library paths, file and folder naming, quality, scheduling, logging, backup, and maintenance options.
General settings control where Comicarr stores files, how it names them, and when background tasks run. Many options live in config.ini; the Settings → General page exposes content sources and naming-related UI controls. Library paths are typically shown read-only in the UI.
Library Paths
| Setting | Type | Default | Description |
|---|---|---|---|
DESTINATION_DIR | string | none | Root directory for your organized comic library. |
CACHE_DIR | string | none | Directory for temporary cache files (covers, API responses). |
GRABBAG_DIR | string | none | Directory for one-off or miscellaneous downloads. |
NEWCOM_DIR | string | none | Directory where newly downloaded comics land before processing. |
In Docker, these paths refer to container-side mount points. Make sure the corresponding volumes are mapped in your docker-compose.yml.
Content Sources
Control which metadata providers are active. At least one source must be enabled.
| Setting | Section | Type | Default | Description |
|---|---|---|---|---|
COMICVINE_ENABLED | [CV] | bool | True | Enable comic content via ComicVine. |
MANGADEX_ENABLED | [MangaDex] | bool | True | Enable manga content via MangaDex. |
When a source is disabled, its search results, metadata features, and library UI elements are hidden. Enable both sources for a mixed comic and manga library. Disabling a source hides provider-specific functionality and leaves existing data in place.
File and Folder Naming
File Format
| Setting | Type | Default | Description |
|---|---|---|---|
FILE_FORMAT | string | $Series $Annual $Issue ($Year) | Template for renaming comic files. |
Folder Format
| Setting | Type | Default | Description |
|---|---|---|---|
FOLDER_FORMAT | string | $Series ($Year) | Template for series directories. |
Arc Folder Format
| Setting | Type | Default | Description |
|---|---|---|---|
ARC_FOLDERFORMAT | string | $arc ($spanyears) | Template for story arc directories. |
Available Tokens
| Token | Description | Example |
|---|---|---|
$Series | Series name | Amazing Spider-Man |
$Issue | Issue number (zero-padded per ZERO_LEVEL) | 001 |
$Year | Publication year | 2024 |
$Annual | Resolves to Annual when the issue is an annual, empty otherwise | Annual |
$Monthly | Resolves to the month name for monthly issues | January |
$Publisher | Publisher name | Marvel |
$Imprint | Publisher imprint | MAX Comics |
$Type | Series type (e.g. Trade Paperback, Hard-Cover) | TPB |
$arc | Story arc name (arc folders only) | Secret Wars |
$spanyears | Year range the arc spans (arc folders only) | 2015-2016 |
Naming Options
| Setting | Type | Default | Description |
|---|---|---|---|
REPLACE_SPACES | bool | False | Replace spaces in filenames with REPLACE_CHAR. |
REPLACE_CHAR | string | none | Character used when REPLACE_SPACES is enabled (often _ or . when set). |
ZERO_LEVEL | bool | False | Enable zero-padding of issue numbers. |
ZERO_LEVEL_N | string | none | Padding width when ZERO_LEVEL is enabled. |
LOWERCASE_FILENAMES | bool | False | Force all filenames to lowercase. |
Quality Settings
Configured under Settings → Search for the UI-exposed filters, or in config.ini.
| Setting | Type | Default | Description |
|---|---|---|---|
PREFERRED_QUALITY | int | 0 | Preferred release quality: 0 = any, 1 = HD, 2 = Web-DL. |
MINSIZE | string | none | Minimum file size in MB when USE_MINSIZE is enabled. |
MAXSIZE | string | none | Maximum file size in MB when USE_MAXSIZE is enabled. |
USE_MINSIZE | bool | False | Enable the minimum size filter. |
USE_MAXSIZE | bool | False | Enable the maximum size filter. |
Scheduling
All intervals are in minutes unless noted otherwise.
| Setting | Type | Default | Description |
|---|---|---|---|
RSS_CHECKINTERVAL | int | 20 | Minutes between RSS feed checks. |
SEARCH_INTERVAL | int | 1440 | Minutes between full search sweeps (default is 24 hours). |
DOWNLOAD_SCAN_INTERVAL | int | 5 | Minutes between download client status polls. |
CHECK_GITHUB_INTERVAL | int | 360 | Minutes between update checks against the GitHub repository. |
Setting RSS_CHECKINTERVAL or SEARCH_INTERVAL too low may cause you to hit provider rate limits. The defaults are safe for most setups.
Logging
Comicarr has exactly one verbosity control. The level it resolves to is applied identically to the console, comicarr.log, and the log list in the web UI. There is no separate "quiet" switch and no per-subsystem dial.
| Setting | Section | Type | Default | Description |
|---|---|---|---|---|
LOG_DIR | [Logs] | string | none | Directory for log files. Defaults to <config_dir>/logs. |
MAX_LOGSIZE | [Logs] | int | 10000000 | Maximum log file size in bytes (~10 MB). |
MAX_LOGFILES | [Logs] | int | 5 | Number of rotated log files to keep. |
LOG_LEVEL | [Logs] | int | 1 | Verbosity. See the table below. |
Levels
| Level | Name | What is emitted |
|---|---|---|
0 | warning | Warnings and errors |
1 | info (default) | Info and above |
2 | debug | Everything |
Level 0 still writes failures to the log; it is quieter, never silent. Values outside 0 to 2 are clamped instead of rejected.
Every source accepts either notation, case-insensitively: debug and 2 mean the same thing on the command line, in the environment, and in config.ini. The value stored in config.ini is always the integer.
Where the level comes from
Three sources, highest priority first. A source counts only when it explicitly supplies a value, so an unset one leaves the layer beneath it alone.
| Priority | Source | Set by |
|---|---|---|
| 1 | --log-level N startup argument | Command line, systemd unit, container entrypoint |
| 2 | COMICARR_LOG_LEVEL environment variable | Compose file, shell |
| 3 | LOG_LEVEL in config.ini | Settings → Logs |
If none supplies a value, the level is 1. Whichever source wins announces at startup what it overrode:
Log level 2 (debug) from startup argument overrides 1 (info) from the config file--verbose / -v and --quiet / -q still work as deprecated aliases for --log-level debug and --log-level warning.
Settings → Logs
The Logs section of Settings holds the level dial and a viewer for the tail of comicarr.log. Filter it by severity, pull a 200, 1,000, or 5,000 line window, and copy the result into a bug report. Provider secrets are redacted before any line leaves the server, and only the current log file is read; rotated files stay on disk.
A level saved here applies immediately, with no restart. When a --log-level flag or COMICARR_LOG_LEVEL is pinning the level, the page says so and names three separate numbers: the level actually running, the level saved in config.ini, and the level the next restart will resolve to. They are allowed to differ, which is why the page reports all three.
Starting a new log
Since v0.35.0 the Logs page has a New log button. It rolls comicarr.log over so the viewer shows only what happens after you click, which is what you want when reproducing a problem. Comicarr asks for confirmation first, and the previous file is kept as a rotated archive under your existing MAX_LOGFILES retention. If logging is running without a file sink, the button clears the viewer and says so.
Diagnosing folder scans
The old FOLDER_SCAN_LOG_VERBOSE switch was removed during the config upgrade. Folder-scan diagnostics follow the single dial, so set level 2 · Debug when investigating scan matching.
Backup
| Setting | Type | Default | Description |
|---|---|---|---|
BACKUP_ON_START | bool | False | Create a backup of the database and config each time Comicarr starts. |
BACKUP_LOCATION | string | none | Directory for backup files. Defaults to <config_dir>/backups. |
BACKUP_RETENTION | int | 4 | Number of backup copies to retain. Older backups are deleted automatically. |
Maintenance
| Setting | Type | Default | Description |
|---|---|---|---|
CLEANUP_CACHE | bool | True | Periodically remove stale cache files. |
CLEANUP_STRAYS | bool | False | Remove orphaned files that no longer belong to a monitored series. |