Upgrading to 2.0#

MetaTana 2.0 is coming soon. It replaces the 1.x sidebar of fourteen pages with seven, and moves several Settings tabs. Your library, edits and saved keys carry over. This page is the one place that lists what changed from 1.x and what to check after you update.

How To Update#

1. Desktop (macOS, Windows, Linux AppImage)MetaTana offers 2.0 in its update dialog. In 1.x the check is under Settings → General → Updates, and on macOS also MetaTana → Check for Updates. Choose Restart when the download finishes. Linux .deb and .rpm installs update through apt, dnf, yum, or your normal package workflow. See Desktop installation: updates.
2. DockerStop MetaTana and back up the /app/data volume, then pull and recreate the container with the same volume mapping: docker compose pull && docker compose up -d. The stable tag moves to 2.0; a pinned version tag such as 1.1.14 stays on 1.x until you change it. See Docker installation: update or pin a release.
3. UnraidStop MetaTana and back up /mnt/user/appdata/metatana, then update MetaTana when Unraid offers it. Keep the mapping from the appdata folder to /app/data. See Unraid installation: updates and backups.
4. TrueNASBack up the app-data dataset or ixVolume, then use Apps → MetaTana → Update when TrueNAS offers 2.0. The TrueNAS catalog is run by outside maintainers, so 2.0 can reach it later than the Docker image.

On the first start, MetaTana writes the Before upgrade backup to the backups folder in its app data (/app/data/backups on Docker, Unraid, and TrueNAS), then upgrades the database. That copy is the library exactly as 1.x left it, and it lives on the same disk, so keep your own copy too. See Back up your library.

Where The Old Pages Went#

The sidebar now holds Home, Library, Inbox, Folders, Sync and Activity, with Settings and Help at the bottom. Every other place is in ⌘K (Ctrl+K on Windows and Linux) under Go to. Old links and bookmarks open the new place.

Where The Old Settings Tabs Went#

Settings has five sections: General, Account, Providers, Files and Maintenance. Search settings… finds a setting by its old tab name too, and marks it, for example Was “Renamer”. Old Settings links open the new place.

More moves:

• Updates (1.x: Settings → General → Updates) are on Help, with Check for updates, Download and Restart to update.
• The local MetaTana API key (1.x: the API Keys tab) is API key under Settings › Maintenance › Advanced.
• Go to shortcuts changed: G A opens Activity, G H opens Home, and Settings moved from G S to G ,. G D, G P, and G T are gone. Press ? on any page for the full list.

What Carries Over#

• Your library: every title, match, episode, collection, tag, person, watched state and resume position.
• Your edits and locks. Values you typed and locked fields stay as they were.
• Folders and destinations. Each watched folder keeps its type and settings, and each destination and routing rule stays.
• Rename history. Renames and moves made in 1.x can still be undone from Activity.
• Multi-episode files. Files such as Show.S01E01-E03.mkv that 1.x stored as their first episode are filled in with every episode they cover.
• Saved keys and sign-ins: provider keys, AI keys, the local API key, the Trakt sign-in, media server sign-ins and webhooks.
  • On the desktop app, the first start of 2.0 encrypts them with your system keychain (macOS Keychain, Windows data protection, or the Linux Secret Service or KWallet). From then on they open only on that computer. See API keys: where saved keys are stored.
  • On Docker, Unraid and TrueNAS they stay in the database as before. Keep the data volume private.
• Settings. Each setting keeps its value in its new place.

After You Update#

1. Sign in with your own accountEach install now belongs to one MetaTana account. An updated install links the account that was already signed in: the account from a browser that still has an open MetaTana session, or the account MetaTana saved for background work (including one set with METATANA_HOSTED_SESSION_TOKEN). If there is none, the first account to sign in after the update becomes the owner. Other accounts see This MetaTana is linked to a different account. See One account per install.
2. Add your domain if you use oneIf you open MetaTana through your own domain, a reverse proxy, or a tunnel, add that name to METATANA_ALLOWED_HOSTS, ideally before you update. Without it the page shows 421 Misdirected Request. Opening MetaTana by IP address or a local name such as nas.local needs nothing. See Your own domain or reverse proxy.
3. Check how each folder handles filesFile handling is now set per folder on Folders: Tidy into Movies and TV folders, or leave files where they are, plus Rename files in this folder. The 1.x global organize switch is gone. If it was off, every folder that had no choice of its own is set to leave files in place, and the old permission to rename without asking is removed.
4. Check Dry run1.x Dry run is Preview only (no file changes) in Settings › General › Scanning, and it now also stops Autopilot and Arrivals from changing files. If it was on when you update, Home shows a one-time notice, Preview only is on, so Autopilot changes no files, with Turn off Preview only and Keep it on.
5. Check hooks and webhooksHooks and webhooks now need Pro. On Free, saved ones are kept and run again after you upgrade. Queued subtitle fetches and automatic hook runs wait in Activity with an Upgrade to Pro note.
6. Docker without a browser openHooks, webhooks and the metatana command-line tool confirm Pro through a signed-in browser, and that lasts 24 hours. If nobody opens this install in a browser, set METATANA_HOSTED_SESSION_TOKEN in the container environment.
7. Desktop: keep old copies privateCopies of the app data folder and database backups made before the update still hold saved keys as plain text. Keep them private or delete them.

What Works Differently#

• Hosted AI credits. Autopilot and other background runs never spend hosted AI Vision credits, and the Allow Autopilot to spend hosted AI credits setting is gone. AI Scrape runs when you ask for it.
• Incoming folders. New arrivals always wait in the Inbox for your approval; the Add new files automatically when the match is Good switch from the 1.x Setup tab is no longer shown. Approve all Good adds every Good match in one step.
• Read-only folders scan and are watched like any other folder. Only file changes need write access.
• Quick edit locks the values it writes only when you tick Lock after editing. In 1.x it always locked Genres, Certification, and Note.
• Trakt marks only the episode you watched. In 1.x a watched episode could add every episode of the show to your Trakt history.
• NFO rewrites from Metadata tasks follow the Flavour in Settings › Files › NFO files. In 1.x they always wrote Kodi-style NFO.
• Plex artwork names. For Plex, MetaTana writes poster.jpg and fanart.jpg in show and movie folders. 1.x named them after the media file.
• Show folders include the year in the default naming patterns. Existing show folders are not moved, and patterns you saved are kept. See Naming and organizing.
• Translations pick the language from a list and confirm the credit before anything runs.

If Something Looks Wrong#

• Startup stops with a data folder error on Docker. 2.0 checks that the data volume is writable by the configured user. Fix the volume permissions or PUID/PGID, then restart.
• A saved key shows "Can’t be opened here". The app data folder came from another computer or the keychain was reset. Paste the key again. See API keys.
• You need 1.x back. Stop MetaTana, put back the copy of the app data folder you made before updating, then install 1.x or change the Docker tag. Changing the tag alone does not roll the database back, and 1.x cannot open a library that 2.0 has upgraded.

The changelog will list every change when 2.0 is out.