Back Up Your Library#

MetaTana stores everything it knows about your library in a single SQLite database plus the sidecar files on disk next to your media. MetaTana backs up that database for you every day and before each upgrade, and you can restore any backup from Settings › Maintenance › Backups. This recipe covers backups, restores, writing NFO files so other apps can read your metadata, and exports.

Step 1: Open Backups#

Open Settings › Maintenance and find Backups, or press ⌘K (Ctrl+K on Windows and Linux) and pick Settings: Backups. The group has:

• the database backups (copies of the library database)
• Settings file: a small JSON file with your settings, without provider keys
• Import a tinyMediaManager setup
• Export N titles: a CSV, HTML, XML, or Excel inventory of your library

None of them writes NFO files; Step 4 covers that.

The Settings file is for moving a setup to another install. Export… saves it, and Restore… in its ⋯ menu loads one. It doesn't contain the library or your provider keys, and restoring it leaves your saved keys as they are. Import a tinyMediaManager setup is covered in Migrate from tinyMediaManager.

Step 2: Check your database backups#

MetaTana makes these copies on its own:

Backups shows the latest two copies with their kind, and Restore… opens Restore a database backup with the six newest copies (date, kind, and size); Show N older lists the rest. Older copies of the same kind are removed when a new one is made. MetaTana skips a copy when the disk would have less than 256 MB free afterwards. A reset is different: if MetaTana cannot save the Before reset copy, the reset does not run.

1. Select Back up nowDo this before bulk rescrapes, anime mode changes, moving your media folders, or anything else that touches many titles.
2. Confirm the new rowA Manual row with today's date appears at the top of the list.

Backups live in a backups folder next to the database: data/backups/ in the app's data folder, or /app/data/backups in Docker. The desktop app has Open backups folder. Backups sit on the same disk as the database, so they help with a bad update, a bad edit, or a damaged database file, not with losing the disk. Copy the backups folder to another drive if you need that.

For protection against losing that disk, also copy the app data folder (including backups) and anything you need to reconnect providers and media servers. Quit MetaTana (or stop the container) first: never copy only a live SQLite file while MetaTana is running.

Step 3: Restore a backup#

1. Select Restore…Pick the backup from before the problem started.
2. Select Restore on restartThe restore does not run right away. MetaTana checks the backup first and refuses one that is damaged, incomplete, or made by a newer version.
3. Restart MetaTanaThe page says Restart MetaTana to restore the backup from …. On desktop, select Restart now. In Docker, restart the container. Changed your mind? Select Cancel restore before restarting.
4. Check the resultAfter the restart, the page says Restored the backup from …. The database from before the restore is kept as a Before restore backup, so you can go back.

If the current library database is damaged, MetaTana can't make a Before restore copy of it. It renames the damaged file to metatana.db.corrupt- in the data folder instead and goes ahead with the restore, so nothing is lost. You can delete that file once the restored library looks right.

Restoring on another computer, or after your system keychain was reset, brings the library over but not the keys it encrypted: Settings › Providers says Saved keys can't be opened on this computer, with Clear saved keys, and MetaTana makes a new local API key. Folders show Offline until you reconnect them. See Move or restore a library.

If MetaTana can't start at all, see If MetaTana can't open: the desktop recovery window and the metatana backup command restore the same backups. The command is in Reference: CLI.

Step 4: Write NFO files for portability#

NFO files next to your media keep the metadata readable by other apps (Kodi, Jellyfin, Emby, Plex via plugins) even without MetaTana running.

• Selected titles: in Library, select titles and choose More › Write NFO. For one title, use Write NFO in its ⋯ menu.
• Out-of-date NFO files: in Library, open Needs attention › NFO out of date and select Rewrite files for N. Show all › Metadata tasks › Stale sidecars › Repair shown does the same from the task lists.

Writes run in the background and appear in Activity. Existing NFOs are updated in place: MetaTana replaces the fields it manages and keeps unknown or hand-added XML. They use the format set in Settings › Files › NFO files. See NFO and artwork.

Export N titles is different: it saves an inventory file for spreadsheets and audits, not NFO files. See Export your library.

Export your library#

An export is an inventory of your library for spreadsheets and audits, not a backup. Use one for:

• auditing a library
• comparing metadata between runs
• sharing non-sensitive inventory
• checking provider IDs and people fields
• validating rename token coverage

Export… on the Export N titles row in Backups exports the whole library. The drawer has Format, Columns with Select all and Clear, and Export.

Export from Library#

Export… in the Library ⋯ menu, or in the bulk menu for a selection, opens Export Library:

• Items: Selected items, Current view (the active search, type, and filters), or Whole library.
• Format: CSV, JSON, XML, Excel, HTML list, or one of your templates. These formats are also available from the CLI.
• Fields: the columns for built-in formats, including Certification, Release Date, TMDb Rating, IMDb Rating, Completeness Score, File Size, Audio Codec, and Audio Channels.
• Save to: Download, or A folder with Browse. The folder is on the machine running MetaTana (a container path on Docker). An existing file is never replaced; the new one gets -2, -3, and so on.
• Show first 5 items previews the output before you export.

Export templates#

Export templates… (in the ⋯ menu on the Export N titles row in Settings › Maintenance › Backups) lets you build your own layout, such as a Markdown list or a custom HTML page. Select New template, set Name, File type (the extension, such as md or html), and Template, then select Preview. Save template is available only after a preview of exactly what you are saving. Saved templates appear as formats in Library export and can be used with metatana export --template.

Templates use the same field syntax as rename patterns:

Item fields include titles, year, genres, people, ratings, provider IDs, file and stream details, certification, release date, and completeness. The Item fields list in the editor shows them all. Values are escaped for the file type: HTML for html, XML for xml and nfo, CSV quoting for csv, JSON string escaping for json, and plain text for anything else. Templates never run code.

If your saved templates don't load, the card says Couldn't load your templates. Editing is paused so your saved templates aren't replaced. Select Retry. New template comes back once they load.

If another window saved templates after you opened yours, your save does not overwrite them. The card says This list changed in another window, loads the latest list, and asks you to make your change again.

A failed template load in Library's Export Library also shows an error with Retry. Built-in formats still work. Retry keeps your export choices and preview.

If MetaTana can't open#

The desktop recovery window has Restore a library backup. It lists the backups without opening the current database or asking for Pro. Choose a backup and select Restore and Restart. MetaTana stops its web and background processes, selects the backup, then restarts.

On Docker, stop the container before using the offline commands. For the Compose setup in the installation guide:

docker compose stop metatana
docker compose run --rm --no-deps metatana metatana backup list
docker compose run --rm --no-deps metatana metatana backup restore BACKUP_ID --confirm
docker compose up -d metatana

Replace BACKUP_ID with an ID from the list. The one-off command uses the same data volume and configured user. In a split setup, stop both metatana-web and metatana-background; run the offline command with the metatana-web service, then start web first and wait for its health check before starting background.

Library upgraded by a newer MetaTana#

MetaTana does not open a library that a newer version already upgraded, for example after going back to an older app or Docker tag. It leaves the library unchanged.

• Desktop: the recovery window says which version upgraded the library and shows Restore Backup from the date of the backup taken before that update. Select it and confirm. MetaTana saves a copy of the newer library first, then restarts on the backup. You can also update MetaTana instead.
• Docker: the container stops, and its log names the backup to restore. metatana backup check in the one-off command above prints the same. Restore that backup with the commands above, or use the newer image again.
• If no backup from before the update exists, update MetaTana, or restore your own copy of the data folder from before the update.

Restoring and resetting refuse to replace the database while another MetaTana process still has it open. If a killed container left owner records behind, stop every app, container, and computer sharing that volume before running metatana backup unlock --confirm-stopped through the same one-off command. Normal startup never clears uncertain owners. If MetaTana cannot save the current database before a restore, it stops and leaves those files alone.

Check a restore#

After a restore or migration:

1. Open the appThe first launch after a restore may take a few seconds longer than usual. After an in-app restore, Settings › Maintenance › Backups names the backup that was restored.
2. Confirm the data folderThe desktop app shows it under Settings › Maintenance › Data & diagnostics. Check that it matches where your restored data lives.
3. Check Library countsCompare with the count before the restore. A sudden zero or low count means the wrong database is loaded.
4. Open a few titlesPick a few movies and a show. Their pages should load normally.
5. Check folder pathsOn Folders, confirm each folder is online. On another computer, folders show Offline until you reconnect them; see Move or restore a library.
6. Run Library healthIn Settings › Maintenance › Library health, look for ghost entries from files that moved, untracked files, and broken sidecar files.
7. Test one small sidecar write firstUse Write NFO on a single title. Confirm the file lands on disk before running bulk actions.

What success looks like#

• Backups lists a copy from today
• After a restore, Backups names the backup that was restored and lists a Before restore copy
• If you wrote NFOs: media folders now contain .nfo files alongside the media files

Going deeper#

• NFO and artwork: what gets written into each NFO and artwork file
• Library health: checking disk against the database after a restore
• Move or restore a library: reconnect folders after a move, or restore on another computer
• Recover from a bad rename: when one change needs undoing
• Reference: file layout: where the database, backups, and NFO files live on disk