Cleanup your audiobook collection.

Shelfarr automatically proposes clean, consistent filenames using embedded tags and optional Audiobookshelf metadata. Preview everything first, batch apply, and undo when needed.

Get Shelfarr (Docker Hub) Quick start Configuration View on GitHub

Join the Shelfarr community

Come chat about naming edge cases, share template ideas, and request features. If something hurts in your library, we want the real examples.

Join Discord Request a feature

What you get

A focused tool with the right defaults: fast scanning, safe renames, and human-friendly review.

Preview-first workflow

Everything is proposed before it’s applied. Start with dry-run and enable backups when you’re ready.

Metadata-aware naming

Uses embedded tags and can cross-check Audiobookshelf for better titles and authors.

Consistent templates

Use {author}, {series}, {title} and folders to standardize your library.

Quick start (Docker Compose)

Run Shelfarr locally and mount your library at /library.

docker-compose.yml

services:
  shelfarr:
    image: vacantlycrushing/shelfarr:latest
    ports:
      - "5055:5055"
    environment:
      PORT: "5055"
      ABR_SETTINGS_DB: "/data/settings.db"
      ABR_HISTORY_LOG: "/data/shelfarr_history.jsonl"
      ABR_LOG_FILE: "/data/shelfarr.log"
    volumes:
      - ./data:/data
      - /path/to/your/audiobooks:/library
    restart: unless-stopped

Then run

docker compose up -d

Open http://localhost:5055, point Shelfarr at your mounted folder, and start a scan.

If you run on a NAS or remote host, mount your SMB/NFS share on the host first and pass it into the container.

Run locally (Python)

Prefer not to use Docker? Run the server directly on macOS, Windows, or Linux.

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
PORT=5055 python3 app.py

Open http://localhost:5055. Use normal filesystem paths (e.g. /Users/you/Audiobooks).

Windows (PowerShell)

py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
$env:PORT = "5055"
py .\app.py

Use Windows paths in the UI (e.g. D:\Audiobooks).

Shelfarr is a server app: it runs on the machine where you start app.py (or inside your Docker container). Your browser is only the UI client.

Configuration

Most settings are available in the UI. These environment variables are useful for deployment.

# Server
PORT=5055

# Paths (persist these)
ABR_SETTINGS_DB=/data/settings.db
ABR_HISTORY_LOG=/data/shelfarr_history.jsonl
ABR_LOG_FILE=/data/shelfarr.log

# Audiobookshelf (optional)
ABS_BASE_URL=http://audiobookshelf:13378
ABS_TOKEN=YOUR_ABS_API_TOKEN

# Safety
ABR_DRY_RUN=1
ABR_BACKUP=1

Screenshots

A quick look at scanning and stats.

Scan preview showing proposed renames — Scan preview: proposed renames with confidence and review status.

Stats dashboard — Stats: scan history, totals, and matching quality indicators.

FAQ

Will it overwrite files?

No. Shelfarr refuses to overwrite existing targets. Start with dry-run, then enable backups.

Can it create folders?

Yes—if you enable directory moves and use folder-style templates like {author}/{series}/{title}.

Is ABS required?

No. You can rename using embedded tags only and still get clean, consistent results.