KiCad Library Auto-Consolidation

All custom component libraries live in Libraries/. A consolidation script and file watcher automatically merge everything into two unified libraries (!Custom symbols and footprints) that KiCad loads globally.

How it works

Libraries/
  SomeComponent/           <-- drop a new component folder here
    KiCad/
      SomeComponent.kicad_sym   (or .lib)
      SomeComponent.kicad_mod   (or .mod)
  AnotherComponent/
    AnotherComponent.kicad_sym
    AnotherComponent.kicad_mod
  ...
  consolidate.py           <-- merges everything into:
  _AllSymbols.kicad_sym    <-- one symbol library (all parts)
  _AllFootprints.pretty/   <-- one footprint library (all footprints)
  watch_and_rebuild.sh     <-- triggered by launchd on file changes

When you add a new component folder, macOS launchd detects the change and runs consolidate.py --install, which:

1. Converts legacy formats – .lib (KiCad 5) and .mod (KiCad 4) are converted to modern .kicad_sym / .kicad_mod
2. Merges all symbols into _AllSymbols.kicad_sym
3. Copies all footprints into _AllFootprints.pretty/
4. Fixes footprint references – rewrites symbol footprint fields to !Custom:FOOTPRINT_NAME
5. Strips LIB_ prefixes from component names
6. Upgrades footprint format – converts (module ...) to (footprint ...)
7. Installs to KiCad 9 – updates sym-lib-table and fp-lib-table in KiCad’s global config

The libraries appear as !Custom (the ! sorts them to the top of the chooser).

After consolidation runs, reopen the Place Symbol dialog in KiCad to pick up the changes (no full restart needed).

Supported formats

Non-KiCad EDA formats (CADSTAR, Altium, EAGLE, PADS, DesignSpark subdirectories) are automatically excluded.

Setup on a new machine

Prerequisites

• KiCad 8 or 9 installed at /Applications/KiCad/KiCad.app (macOS) – the script auto-detects the path
• Python 3 on PATH
• KiCad’s bundled Python (ships with KiCad, used for legacy .mod conversion)

Step 1: Clone / copy the Libraries folder

Place it wherever you like, e.g. ~/projects/KiCAD/Libraries/.

Step 2: Run consolidate once manually

cd ~/projects/KiCAD/Libraries
python3 consolidate.py --install

This builds the consolidated libraries and registers them with KiCad. Verify it works by opening KiCad – you should see !Custom at the top of both the symbol and footprint library lists.

Step 3: Set up the file watcher (macOS launchd)

Create the plist file – update the paths to match your setup:

cat > ~/Library/LaunchAgents/com.tom.kicad-lib-watcher.plist << 'EOF'
<?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.tom.kicad-lib-watcher</string>

    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOUR_USERNAME/projects/KiCAD/Libraries/watch_and_rebuild.sh</string>
    </array>

    <key>WatchPaths</key>
    <array>
        <string>/Users/YOUR_USERNAME/projects/KiCAD/Libraries</string>
    </array>

    <key>ThrottleInterval</key>
    <integer>5</integer>

    <key>StandardOutPath</key>
    <string>/tmp/kicad_lib_consolidate.log</string>

    <key>StandardErrorPath</key>
    <string>/tmp/kicad_lib_consolidate.log</string>
</dict>
</plist>
EOF

Load it:

launchctl load ~/Library/LaunchAgents/com.tom.kicad-lib-watcher.plist

Step 4: Verify

Drop a new component folder into Libraries/, wait a few seconds, then check the log:

tail -20 /tmp/kicad_lib_consolidate.log

You should see the consolidation output with your new component included.

Managing the watcher

# Check if running
launchctl list | grep kicad-lib-watcher

# Stop
launchctl unload ~/Library/LaunchAgents/com.tom.kicad-lib-watcher.plist

# Start
launchctl load ~/Library/LaunchAgents/com.tom.kicad-lib-watcher.plist

# View log
tail -f /tmp/kicad_lib_consolidate.log

Manual rebuild

If you need to rebuild without the watcher:

cd ~/projects/KiCAD/Libraries
python3 consolidate.py           # build only
python3 consolidate.py --install # build + register with KiCad

Linux setup

The consolidation script works on Linux too (auto-detects ~/.config/kicad/9.0/ for config). Replace the launchd watcher with inotifywait:

# Install: sudo apt install inotify-tools
while inotifywait -r -e create,modify,delete ~/projects/KiCAD/Libraries/; do
    sleep 2
    cd ~/projects/KiCAD/Libraries && python3 consolida

*[README truncated]*

## Recent Activity

- `7467d1b` updates for 3D models (2026-03-16)
- `d07de0a` added gps libs and auto add to KiCAD script (2026-03-15)
- `c6b75cd` added right angle push button (2025-07-02)
- `b2e37ff` added 0pt4048 (2025-06-11)
- `cfcee47` Merge branch 'master' of github.com:td0034/KiCAD (2025-05-22)

## Languages

- **AGS Script**: 30%
- **ASL**: 22%
- **Perl**: 11%
- **JavaScript**: 10%
- **HTML**: 8%
- **Roff**: 7%
- **Mathematica**: 4%
- **CSS**: 3%
- **Makefile**: 2%
- **C**: 1%
- **OpenEdge ABL**: 1%