Audiobookshelf library empty after a Docker update (and moving to a new computer)

If your Audiobookshelf library is empty after a Docker update, check that the new container still uses your original folders. A folder that was never mapped to your computer lived inside the old container and was removed with it. A mapping that now points somewhere else looks the same at first. Check the paths before you assume anything is deleted.

Audiobookshelf keeps everything in three places. Each one needs a volume line in your compose file: a line that connects a folder inside the container to a real folder on your computer, so it survives when the container is replaced.

Inside the container	What’s in it	If it isn’t mapped
/config	The database: users, libraries, listening progress, settings	You get the “create your admin account” screen after an update
/metadata	Covers, author photos, backups, logs	Covers and author photos disappear, and so do your backups
/audiobooks, /podcasts	Your books and podcast episodes	Books you uploaded through the web app are gone

A correct compose file maps all of them:

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    ports:
      - 13378:80
    volumes:
      - /srv/abs/config:/config        # must be on a local disk
      - /srv/abs/metadata:/metadata
      - /srv/media/audiobooks:/audiobooks
      - /srv/media/podcasts:/podcasts
    restart: unless-stopped

Why is my Audiobookshelf library empty after updating Docker?

Match what you see to the cause.

The setup screen asks me to create an admin account again

The new container can’t find your database. Either /config was never mapped, or it now points at a different folder.

• It was never mapped. The database lived inside the old container and was removed with it. Unless you have a backup stored outside the container, the users, progress and library settings are gone. Map /config, set the server up again and scan your books.
• It points somewhere else. This is common with relative paths like ./config. Those are read from the folder the compose file is in, so moving the compose file, or redeploying it from a tool like Portainer that keeps its own copy, can create a new empty config folder. Look for your old config folder (it holds a file called absdatabase.sqlite), point the volume back at it and run docker compose up -d.

Run docker compose config to see the full host paths Docker is using.

My books uploaded through the web app are gone

The web app’s upload saves files into the library folder inside the container. If /audiobooks (or your library’s folder) wasn’t mapped to a folder on your computer, the uploads only lived inside the container. Recreating it deleted them.

Map the library folder before you upload anything else. Audiobookshelf can’t see my audiobook folder walks through it.

The library is there, but every book is missing

Audiobookshelf can’t see the media folder at the path it remembers. Check:

• The volume line for your books. The inside path (/audiobooks) must be the same as before. The library remembers that path, not the one on your computer.
• Mounts that aren’t ready yet. If the books are on an external drive or a NAS (a storage box on your network), Docker may have started the container before the mount was ready. See Audiobookshelf stops working after a reboot.

Don’t remove the missing books while you fix this. Once the folder is back, a scan matches the books to the old entries and your progress returns.

Covers and author pictures are missing

These live in /metadata. Covers are kept in /metadata/items (unless you turned on Store covers with item), author photos in /metadata/authors, and resized copies in /metadata/cache. When /metadata isn’t mapped, an update wipes them. The maintainer explained this in #4735.

To get them back, map /metadata, then restore a backup. Covers and author photos are both in it. Without a backup, matching the books again brings back their covers, but author photos have to be set again on each author.

Why does Audiobookshelf say “SQLITE_BUSY: database is locked”?

Keep /config on storage attached to the machine running Audiobookshelf, not on a network share. The official Docker guide warns that a database reached over the network, like on a NAS share, may seem fine for a while but gets slow and eventually corrupt.

The error alone doesn’t tell you the cause. If your /config is on a network share, move it to local storage first. Your audiobooks can stay on the share. In #4572, moving /config to a local folder fixed it for one user with the database on a NAS, and a contributor pointed to the same rule.

The issue itself is still open: its reporter has the database on local storage, and a scheduled backup stopped the server with the same error. A restart: unless-stopped line brings it back up.

How do I update Audiobookshelf in Docker safely?

1. Check that /config, /metadata and your media are all mapped (the table above).

2. In the web app, open Settings > Backups and click Create Backup. Download it with the download button next to it and keep the copy somewhere else.

3. Read the release notes for the version you’re moving to.

4. Update:

   docker compose pull
   docker compose up -d
   

If a new version breaks, you can usually go back by changing the image tag to the version you had, for example ghcr.io/advplyr/audiobookshelf:2.36.1, and running docker compose up -d. Audiobookshelf undoes its own database changes when an older version starts. If the older version still won’t run, restore the backup you made in step 2. Audiobookshelf won’t start after a Docker upgrade covers the known startup crashes.

How do I stop automatic Audiobookshelf updates?

Tools like Watchtower check for new images on a schedule and install them on their own. Most of the time that’s fine, but they can also install a faulty release before you’ve had a look. For example, people on some TrueNAS setups saw 2.37.1 fail and restart over and over at startup (#5637). If you’d rather choose when to update, leave Audiobookshelf out of the auto-updater, or pin a version tag.

How do I update Audiobookshelf on Synology?

Container Manager can keep running the old container after an update. The official Docker guide says to stop the container, then choose Reset under Actions. In Portainer, use Recreate. Either one deletes whatever isn’t in a mapped folder, so check your volumes first.

How do I move Audiobookshelf to a new computer and keep progress?

Audiobookshelf saves the full path of every library folder and book. Moving works when those paths stay the same. With Docker, those are the paths inside the container, so the folders on the new computer can be anywhere.

Copy the folders (Docker to Docker)

1. On the old computer, stop Audiobookshelf: docker compose down.
2. Copy the config and metadata folders, your audiobooks and your podcast files to the new computer.
3. Use the same compose file on the new computer, with the left side of each volume line changed to the new locations. Keep the right side (/config, /metadata, /audiobooks and so on) exactly as it was.
4. Run docker compose up -d and sign in with your old account.

Restore from a backup

1. On the old server, open Settings > Backups and click Create Backup. Download it with the download button next to it.
2. Copy your audiobook and podcast files to the new computer. On the new server, map them at the same inside paths as before (/audiobooks, /podcasts).
3. Open Settings > Backups, click Upload Backup, pick the file, then click Restore next to it. Read the warning and click Restore again to confirm.

A backup holds the database (users, progress, library details, settings) and the covers and author photos from /metadata/items and /metadata/authors. It doesn’t include your audiobook files, or covers saved inside the book folders. Restoring replaces the new server’s database (its users, progress and libraries) with the one in the backup. Your media files aren’t touched.

Backups are saved in /metadata/backups unless you change Backup Location, and Automatic backups is off until you turn it on. If /metadata isn’t mapped, your backups disappear with the container too.

Moving between Windows, Linux and Docker

Switching install methods is harder. The official backup docs put it plainly: “Backups cannot be loaded from another installation method without losing progress and metadata.” Windows paths like D:\Audiobooks don’t match Docker paths like /audiobooks. The official migration page has best-effort steps, with no guarantee. If you think you’ll move later, starting on Docker makes it a folder copy.