Clean up your audiobook collection

Shelfarr is a free, open-source bulk audiobook renamer that proposes clean, consistent filenames using embedded tags and optional Audiobookshelf metadata. Preview changes before applying them, rename in batches, and undo when needed.

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

Join the Shelfarr Community

Shelfarr gets better by handling real audiobook libraries. Join the Discord to work through difficult rename cases, share examples, and suggest improvements. If a filename or structure isn’t right, this is where it’s resolved.

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 Safe

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

Metadata-aware naming Smart

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

Consistent templates Flexible

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.

Tasks — Inbox: Manage exceptions & history from one place (even your navbar!).

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

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

History: scan history and undo functionality.

FAQ

What integrations does Shelfarr support?

Shelfarr works with common audiobook file formats, including M4B, M4A, and MP3. For metadata, it can optionally pull information from Audiobookshelf, alongside embedded tags already present in your files.

What if my audiobooks have incomplete or correct tags?

Shelfarr doesn’t assume your tags are perfect. It shows you what it finds, highlights uncertain matches, and lets you fix or override details before anything is renamed.

Does Shelfarr rename files automatically?

No. Shelfarr always shows you a preview before anything is renamed. You stay in control of what changes are applied, which makes it safe to use even on large or messy libraries.

How do i rename audiobooks in bulk?

Shelfarr scans your audiobook files, reads embedded tags and optional metadata, and proposes clean, consistent filenames based on your chosen template. You can review all changes first, apply them in batches, and undo them if needed.

Can Shelfarr handle multi-part audiobooks?

Yes. Shelfarr detects multi-part audiobooks and offers sensible grouping options. You can review how parts are grouped, switch between handling modes, and choose what fits your library before applying changes.