marcus Lightroom Catalog Index
Build a searchable SQLite+FTS5 index from Adobe Lightroom CC's internal catalog on macOS. Extracts photo metadata (EXIF, ratings, keywords, dimensions, camera info) into a clean, queryable database.
Prerequisites
- macOS with Adobe Lightroom CC installed
- Python 3.8+
pip install msgpack
Quick Start
1. Find the catalog
Lightroom CC stores its catalog at:
~/Pictures/Lightroom Library.lrlibrary/*/Managed Catalog.mcat
The script auto-detects this. To verify:
ls ~/Pictures/*.lrlibrary/*/Managed\ Catalog.mcat
2. Run initial ingest
python3 scripts/lightroom-index.py ingest --full
This creates ./lightroom.db with all photo metadata. A 200K+ photo library takes about 2 minutes.
3. Search
python3 scripts/lightroom-index.py search "sunset"
python3 scripts/lightroom-index.py search "*" --rating 4 --year 2024
python3 scripts/lightroom-index.py stats
Configuration
Three ways to configure paths (in order of precedence):
| Method | Catalog | Database | Originals |
|---|---|---|---|
| CLI flags | --catalog PATH |
--db PATH |
--originals PATH |
| Env vars | LIGHTROOM_CATALOG |
LIGHTROOM_DB |
LIGHTROOM_ORIGINALS |
| Auto-detect | ~/Pictures/*.lrlibrary |
./lightroom.db |
— |
CLI Reference
ingest — Index the catalog
lightroom-index.py ingest [--full]
- Default: incremental (only new/changed photos since last run)
--full: rebuild from scratch- Output: JSON with
assets_indexed,total_revisions,errors,max_sequence
search — Find photos
lightroom-index.py search <query> [filters]
| Filter | Description |
|---|---|
--rating N |
Minimum star rating |
--rating-exact N |
Exact star rating |
--year YYYY |
Capture year |
--edited |
Only edited photos |
--camera TEXT |
Camera model/make substring |
--lens TEXT |
Lens name substring |
--date YYYY-MM-DD |
Exact capture date |
--date-from / --date-to |
Date range (inclusive) |
--limit N |
Max results (default: 20) |
--with-path |
Include file paths (needs --originals) |
Use "*" as query to match all photos (filter-only mode).
stats — Library overview
Returns total assets, rated/edited/keyword counts, rating distribution, top cameras, year distribution.
keywords — Top keywords
lightroom-index.py keywords [--top N]
random — Random rated photo
lightroom-index.py random [--rating N] [--keyword TEXT]
Automated Scheduling (LaunchAgent)
To run incremental ingest nightly, create ~/Library/LaunchAgents/com.lightroom.indexer.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.lightroom.indexer</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/python3</string>
<string>/path/to/lightroom-index.py</string>
<string>ingest</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>LIGHTROOM_DB</key>
<string>/path/to/lightroom.db</string>
</dict>
<key>StartCalendarInterval</key>
<dict>
<key>Hour</key>
<integer>1</integer>
<key>Minute</key>
<integer>0</integer>
</dict>
<key>StandardOutPath</key>
<string>/tmp/lightroom-index.log</string>
<key>StandardErrorPath</key>
<string>/tmp/lightroom-index.log</string>
</dict>
</plist>
Load it:
launchctl load ~/Library/LaunchAgents/com.lightroom.indexer.plist
Verify:
launchctl list | grep lightroom
Reference Files
- references/catalog-internals.md — How Adobe Lightroom CC stores data in .mcat
- references/schema.md — Output SQLite database schema
- scripts/lightroom-index.py — The indexer script