Free thinker, humanist, IT entrepreneur

kajfoto: Keep order in Lightroom


A set of Python based utilities under Mac OS/X



In Lightroom, tags are easy to create but hard to keep in order. Renaming tags is doable, but time consuming, and falls into several categories. Keeping hierarchies tidy is even harder. The kajfoto routines makes it easier.



1. How the routines work: Updating the Lightroom Catalog directly

The kajfoto routines directly access the Lightroom Catalog from the command line. The catalog is an SQLite database, typically /Users/yourname/Pictures/Lightroom 4 Catalog.lrdat.

Before using the routines, quit Lightroom and make a backup copy of the catalog. The next time you start Lightroom, the changes will be reflected in the Lightroom keyword hierarchy.


  • kfuse “/Users/yourname/Pictures/Lightroom 4 Catalog.lrdat”
  • kfrename Müncehn München
  • kfmerge Munich,Minga,Munique München
  • kfhier Bayern Augsburg,München,Nürnberg


2. Installing kajfoto: Prerequisites and steps

Prerequisites: An environment with Python 2.7.2 or a higher 2.x version.

Copy the Python scripts into your path. Ensure the files are executable.

3. kfuse: Select the desired Lightroom catalog

Identify the directory and file name of the Lightroom catalog you desire to work on.

As your first kajfoto command, issue kfuse for that catalog. Note that you will probably need to use quotes around the filename, as the default Lightroom catalog contains blanks:


kfuse “/Users/yourname/Pictures/Lightroom 4 Catalog.lrdat”

The selected Lightroom catalog is saved into the kf.conf file

 4. Key kajfoto commands

4.1 kfrename: Change spelling of keywords

If you have used only one version of a keyword, and it’s misspelt or otherwise wrong, you can rename it. The syntax is easy enough:

  • kfrename <old> <new>


  • kfrename Londno London

Successful execution:

  • Tag Londno renamed to London (3441 occurrences)

Sample error message:

  • Tag Londno does not exist in /Users/yourname/Pictures/Lightroom 4 Catalog.lrdat

4.2 kfmerge: Ensure you have only one version of each keyword

Having several versions of a keyword is usually unintentional. This scenario is otherwise similar to the kfrename scenario, but differs in that the correct, intended spelling of the keyword already exists. The syntax is this:

  • kfmerge <one>,<or>,<more>,<mistakes> <correct>


  • kfmerge Londres,Londra,Lontoo London

Successful execution:

  • Tag Londres merged to London (98 occurrences)

  • Tag Londra merged to London (311 occurrences)

Sample error message:

  • Tag Lontoo does not exist in /Users/yourname/Pictures/Lightroom 4 Catalog.lrdat

4.3 kfhier: Implement a keyword hierarchy

Having keywords grouped in a hierarchy makes keywords easier to find. However, it’s easy to make mistakes when creating new keywords, so that they’re in the wrong place in the hierarchy. The syntax is this:

  • kfhier <parent> <one>,<or>,<more>,<children>


  • kfrename UK England,Scotland,Wales,”Northern Ireland”

Successful execution:

  • Tag England moved under UK (415 occurrences)

  • Tag Scotland moved under UK (132 occurrences)

Sample error message:

  • Tag Wales does not exist in /Users/yourname/Pictures/Lightroom 4 Catalog.lrdat

  • Tag Northern Ireland does not exist in /Users/yourname/Pictures/Lightroom 4 Catalog.lrdat

Appendix A: The SQLite structure in Lightroom

  • Each tag is saved in a table AgLibraryKeyword and has a numeric ID (id_local) and a textual description (name)

  • Each picture is tagged in a table AgLibraryKeywordImage using the numeric ID (id_local)

  • There can be two types of wrong textual descriptions – misspelt tags and redundant tags

    • Misspelt tags are corrected with kfrename; this is a quick operation, not touching individual images

    • Redundant tags are corrected by updating id_local to point to the right keyword, for each file that references the wrong keyword

Appendix B: Error conditions

  • If a kf command (kfhier, kfrename, kfmerge) is run without a valid kf.conf file, the corresponding kf command gives an error message, either one of these two

  • Lightroom database <x> does not exist; configure a proper one with kfconf

  • Lightroom database not yet configured; configure it with kfconf

Appendix C: Selected other reading




1 Comment

Leave A Reply