Plex Database Repair and Optimization: Fix Corruption and Speed Up Your Server

Your Plex database is a single SQLite file that stores everything about your server except the media files themselves — library metadata, watch history, user preferences, poster artwork links, play sessions, and server configuration. When it works, you never think about it. When it breaks, everything breaks: libraries won’t load, metadata disappears, the server crashes on startup, or performance degrades to the point where browsing your library takes 30 seconds per screen.

Here’s how to diagnose database problems, repair them, and keep them from coming back.

Signs Your Database Needs Attention

• Slow library browsing: Scrolling through your movie or TV library takes noticeably longer than it used to. Pages load in 5–10 seconds instead of instantly.
• Missing metadata: Posters, descriptions, or ratings disappear for some items even though the files haven’t changed.
• Plex crashes or won’t start: The server process exits immediately after launch, often with “database disk image is malformed” in the logs.
• “Database is corrupted” error: Plex explicitly tells you in the web UI or logs. This is the clear-cut case.
• Watch history inconsistencies: Items showing as watched when they aren’t, or On Deck displaying stale episodes.
• Excessive disk usage: The database file (com.plexapp.plugins.library.db) has grown to several gigabytes for a modest library. Normal size for a 5,000-item library is 200–500 MB.

Where Plex Stores Its Database

The database file location depends on your OS:

• Linux: /var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-in Support/Databases/
• Windows: %LOCALAPPDATA%\Plex Media Server\Plug-in Support\Databases\
• macOS: ~/Library/Application Support/Plex Media Server/Plug-in Support/Databases/
• Docker: Inside your mapped /config volume, under the same relative path

The main file is com.plexapp.plugins.library.db. You may also see -wal and -shm companion files — these are SQLite’s write-ahead log and shared memory files. Don’t delete them while Plex is running.

Built-In Repair Tools

Plex has four maintenance operations accessible from Settings → Troubleshooting (or Manage → Troubleshooting in newer versions):

1. Repair Database: Runs SQLite integrity checks and attempts to fix minor corruption. This is the first thing to try and fixes most issues.
2. Clean Bundles: Removes orphaned metadata bundles — artwork and data for items that no longer exist in your library. Reclaims disk space.
3. Optimize Database: Runs SQLite VACUUM and REINDEX, compacting the database file and rebuilding indexes for faster queries. Can dramatically improve browsing speed on bloated databases.
4. Empty Trash: Permanently removes items you’ve deleted from libraries. Until you empty trash, deleted items still exist in the database.

Run them in this order: Repair → Empty Trash → Clean Bundles → Optimize. Wait for each to complete before starting the next. On large libraries (50K+ items), Optimize can take 30–60 minutes.

Manual SQLite Repair

When Plex’s built-in repair fails — usually when the database is too corrupted for Plex to even start — you can repair it manually with the sqlite3 command-line tool.

Step 1: Stop Plex completely

The database must not be in use. Stop the Plex service, verify no Plex Media Server process is running.

Step 2: Back up the current database

Copy com.plexapp.plugins.library.db, .db-wal, and .db-shm to a safe location. If the repair makes things worse, you want to be able to revert.

Step 3: Check integrity

sqlite3 com.plexapp.plugins.library.db "PRAGMA integrity_check;"

If this returns “ok”, the database isn’t structurally corrupted — the problem is elsewhere. If it returns errors, proceed to the dump-and-reimport method.

Step 4: Dump and reimport

sqlite3 com.plexapp.plugins.library.db ".dump" | sqlite3 repaired.db

This exports all recoverable data to SQL, then imports it into a fresh database. Corrupted rows are skipped. Rename repaired.db to com.plexapp.plugins.library.db and start Plex.

You may lose some data — the rows that were corrupted. Usually this means a few items lose their metadata or watch status, which Plex repopulates on the next library scan.

Optimization for Large Libraries

Libraries with 100K+ items (heavy TV show collections) put real strain on SQLite. Some tips:

• Keep the database on an SSD. This is the single biggest performance improvement. SQLite performance is almost entirely I/O-bound, and a spinning disk adds 10–50ms per random read. An SSD drops that to microseconds.
• Schedule weekly optimization. Plex can run Optimize Database on a schedule (Settings → Scheduled Tasks). Set it for 3 AM when nobody is streaming.
• Don’t store the database on a network share. SQLite over NFS or SMB is a recipe for corruption. The locking mechanisms don’t work reliably over network filesystems. Your media files can live on a NAS, but the Plex database must be on a local disk.
• Reduce library scan frequency. If you have Plex scanning every 15 minutes across 10 libraries, that’s constant database writes. Scan daily unless you’re actively adding content, or use webhook-triggered scans from Sonarr/Radarr.

Preventing Corruption

• Use a UPS. The number one cause of database corruption is power loss during a write. A $50 UPS that gives your server 5 minutes of battery is cheap insurance.
• Shut down Plex properly. Don’t just kill the process or pull the power. Use the web UI (Settings → General → Restart/Shutdown) or the system’s service manager.
• Back up regularly. Automate database backups to a separate drive or cloud storage. If corruption happens, you want a recent clean copy to restore from, not a 6-month-old backup that’s missing half your watch history.
• Monitor disk health. A failing drive produces write errors that corrupt databases before the drive fully dies. Watch SMART attributes, especially Reallocated Sectors and Pending Sectors.

When to Rebuild From Scratch

If the database is so corrupted that dump-and-reimport fails, or if the repaired database is still behaving erratically, sometimes the fastest fix is to delete the database entirely and let Plex rebuild from scratch. You’ll lose all watch history, custom metadata edits, and user preferences — but the library structure rebuilds automatically from your files.

Before rebuilding: export watch history from Tautulli (if you have it), note any custom metadata or collection setups you’ll need to recreate, and ensure your media files are properly named so the rescan matches everything correctly.