01
Quit Lightroom to release file locks
Close Lightroom Classic, or open Plug-in Manager and Disable KeywordLens. This frees any locked files so the overwrite is clean.
Upgrade workflow
Move KeywordLens to the newest release in minutes.
Upgrading is an in-place file overwrite. You keep the same keywordlens/ folder, so Lightroom keeps the plug-in registered and your catalog, settings, and credentials carry over untouched.
No re-registration
Because the folder name stays keywordlens/, you do not remove and re-add the plug-in. Lightroom reloads the new code in place.
Latest release
v0.47.0
KeywordLens also checks for this version on plug-in load (when enabled in Advanced settings) and tells you when a newer build is available. Network or website outages stay silent.
02
Download the new release ZIP
Grab the latest keywordlens-v*.zip from the downloads page. You do not need to delete your existing install first.
03
Extract over the same parent folder
Use the command-line extraction below so existing files are overwritten and your data files are left in place. Extract into the same parent directory that already contains keywordlens/.
04
Re-run the setup script
From inside keywordlens/, run setup again so the backend runtime (server/venv) and pack-builder modules match the new code.
05
Reopen Lightroom and confirm
Reopen Lightroom (or Plug-in Manager -> Enable / Reload Plug-in). A small "KeywordLens backend ready" bezel confirms the new backend restarted.
Extract over your install
Use the command line for a clean in-place overwrite.
The -o / -Force flags overwrite existing files. Anything not in the ZIP — most importantly server/.env — is left untouched. Replace vX.Y.Z and the destination path with your own.
- macOS / Linux
unzip -o ~/Downloads/keywordlens-vX.Y.Z.zip -d ~/Tools/ - Windows
Expand-Archive -Force -Path keywordlens-vX.Y.Z.zip -DestinationPath C:\Tools\ - Then
From inside
keywordlens/, re-run setup: macOSbash setup/setup.sh, Windowspowershell -ExecutionPolicy Bypass -File .\setup\setup.ps1.
Your data is safe
What is preserved across an upgrade.
Everything that lives outside the install folder, plus secrets excluded from the release archive, carry over automatically:
~/.keywordlens/keywordlens.db— catalog, analysis state, and the FTS5 search index.~/.keywordlens/server.log— backend log history.~/.keywordlens/offline-packs/— installed offline location packs (when configured there).server/.env— Azure service-principal credentials, excluded from the ZIP at build time so an in-place extract cannot wipe them.- Lightroom preferences — provider choice, API keys for non-Entra providers, and taxonomy assignments.
Before you extract
Two things that trip people up.
macOS Finder Replace wipes the folder. Do not use Archive Utility or Finder's Replace button when extracting on top of an existing keywordlens/. Replace deletes the destination first, taking server/.env with it. Use the unzip -o command above, or click Keep Both and copy server/.env across by hand.
Locale-string changes need a full restart. When release notes mention translated-string changes, fully quit and reopen Lightroom. Lightroom Classic loads TranslatedStrings_*.txt once per process, so Reload Plug-in is not enough.
If the backend will not start
Repair after a broken update.
If the plug-in loads but the backend never becomes ready, run this repair flow from the install root (keywordlens/).
- Open Plug-in Manager -> KeywordLens -> Advanced and click Repair Backend... — it runs preflight checks and prints the exact command to run.
- Re-run setup: macOS
bash setup/setup.sh, Windowspowershell -ExecutionPolicy Bypass -File .\setup\setup.ps1. - Confirm
server/src/main.pyandtools/pack-builder/routes_pack_builder.pyexist, plus a Python runtime (server/venv/or a system Python onPATH). - Reload the plug-in in Lightroom Plug-in Manager.
Need the full picture?
The manual and install guide cover every setting and edge case.
New to KeywordLens, or setting it up on a fresh machine? Start with the install guide. For day-to-day usage and troubleshooting, see the manual.