Absolute path vs KiCad Path variable on MacOS

Software
1

I have my KiCad libraries stored in iCloud Drive and I use the following script to create a list of symbols to append to the end of the KiCad ‘sym_lib_table’ file (in the preferences folder). This works fine and I do the same for other programs, which macOS handles internally without issues.

When I use an absolute path, everything seems to work correctly and the symbols (and footprints) are found properly. I also created a KiCad path variable called ‘KICAD_USER_LIBS’ pointing to my KiCad library folder, which my script translates to entries like:
(lib (name "SparkFun-Battery")(type "KiCad")(uri "${KICAD_USER_LIBS}/symbols/SparkFun/SparkFun-Battery.kicad_sym")(options "")(descr ""))

This format appears similar to the standard entries like:
${KICAD9_SYMBOL_DIR}/Transistor_FET.kicad_sym and shows fine in the symbol manager.

However, although the ‘KICAD9_SYMBOL_DIR’ variable resolves correctly, the ‘KICAD_USER_LIBS’ variable resolves to:
~/iCloud Drive/KiCad/KiCad_libraries/symbols/SparkFun/SparkFun-Battery.kicad_sym

This results in the error message:
“Library file ‘~/iCloud Drive/KiCad/KiCad_libraries/symbols/SparkFun/SparkFun-Battery.kicad_sym’ not found. Error loading symbol library SparkFun-Board.”

For now, I’ve reverted to using the full absolute path, but my question is: Why can’t KiCad resolve the tilde (~) to an absolute path like it should, making the path for KiCad:
/Volumes/Puddle/Users/MeMe/Library/Mobile Documents/com~apple~CloudDocs/KiCad/KiCad_libraries/?

The script that I created. BTW, the same thing counts for my footprint script, the script works fine but the path resolving gets wrong.

symbol_library_path_builder-v2.py (1.9 KB)

2

Short answer: KiCad doesn’t expand ~ — only the shell does. Use an absolute path or ${HOME}, not ~, in path variables and library URIs.

Why your case fails

  • ~ expansion is a shell feature (bash/zsh), not general path syntax. KiCad’s path substitution only handles ${VAR} style variables.
  • KICAD9_SYMBOL_DIR works because KiCad sets it to an absolute path internally; your KICAD_USER_LIBS contains ~, which KiCad leaves literal, so the file isn’t found.

Fixes (pick one)

  1. Preferences → Configure Paths: set KICAD_USER_LIBS to the full absolute path (no ~).
  2. Or set it to ${HOME}/Library/Mobile Documents/com~apple~CloudDocs/… (KiCad will expand ${HOME}).
  3. In your Python script, expand ~ before writing the table: os.path.expanduser(“~/…”).

Notes

  • Spaces in “iCloud Drive” are fine; the issue is the tilde.
  • After updating, restart KiCad or re-open the project so it re-reads the path table.
3

Setting the path variable to ‘${HOME}/Library/Mobile Documents/com~apple~CloudDocs/’ it is.

Thank you.