Good KiCad library management comes down to one rule: anything a project needs lives inside that project, and everything shared is read-only and versioned. Follow it and your design opens on a colleague's laptop, on another operating system, and two years from now, without a "missing library" dialog.
This guide covers how KiCad tracks symbol and footprint libraries, where global and project tables differ, how to set up portable paths, how to use Git without making a mess, and how to survive a major version upgrade.
TL;DR
- KiCad keeps two library tables: a global one for your user account and a project one stored beside the design. Use the project table for anything the design depends on.
- Point project libraries at
${KIPRJMOD}so paths stay relative and the project opens on any machine. - Keep the cache library file in version control. It is the safety net when someone's global setup differs from yours.
- Treat shared libraries as a read-only approved set, and keep your own edits in project-contained libraries.
- When upgrading KiCad, import your old tables and migrate the built-in libraries rather than rebuilding by hand.
Table of Contents
- How KiCad actually tracks libraries
- Where the stock libraries come from
- Global vs. project libraries: a decision rule
- Make project libraries portable with KIPRJMOD
- Use Git, but choose the mechanism deliberately
- Keep the cache library in version control
- Upgrading KiCad without losing your libraries
- A repeatable setup for a new project
- Common problems and the fix
- Our perspective: libraries are half the job, sourcing is the other half
- Check your libraries against real parts
- A short checklist before you share a project
- FAQ
- Sources
How KiCad actually tracks libraries
A KiCad library holds symbols or footprints, never both. KiCad doesn't scan folders. It reads two table files, one for symbol libraries and one for footprint libraries, and the official getting-started guide describes them as the list of libraries to use and where to find them. The files are sym-lib-table and fp-lib-table.
Each table exists at two levels:
| Level | Where it lives | Who it affects | Best for |
|---|---|---|---|
| Global | Your user configuration directory | Every project you open on that machine | The stock KiCad libraries |
| Project | Inside the project folder | Only that project, on any machine | Custom parts, vendor parts, anything the design needs |
The global tables sit in OS-specific folders, such as %APPDATA%\kicad\9.0\ on Windows and ~/.config/kicad/9.0/ on Linux, according to the same documentation. You manage both levels from Preferences, in the symbol and footprint library managers.
The practical consequence: a global entry is a fact about your computer, not about your design. If a schematic only works because of a global entry, it's not portable yet.
What the first-run dialog does
The first time you open the schematic editor, KiCad asks how to set up the global symbol table. The getting-started tutorial recommends copying the default global table if you installed the default libraries. The footprint editor asks the same question. If KiCad can't find the libraries where it expects them, that option is disabled and you browse to a custom sym-lib-table file instead.
This is also the cause of the classic "No Symbol Library Detected" error that readers ask about on forums: the table is empty or missing, so KiCad has nothing to search. Re-adding the default table, or pointing to the right file, fixes it.
Where the stock libraries come from
Most people should simply use the libraries that ship with the installer. KiCad's download page says the libraries are packaged with the installer and OS packages, and that most users don't need to fetch them separately. For KiCad 10, the project hosts four GitLab repositories: symbols, footprints, 3D models and project templates.
That split matters for management. Symbols, footprints and 3D models are separate assets that reference each other by name. A symbol points to a footprint, and a footprint points to a model. Update one without the others and links can quietly break.
Global vs. project libraries: a decision rule
Use this rule of thumb.
- Stock parts from KiCad's own libraries: global tables are fine. Keep them stable.
- Parts you drew, edited or downloaded: put them in a library inside the project, or in a shared library you pin to a specific version.
- Anything a collaborator, contract manufacturer or future you must open: project table only.
Experienced designers also advise keeping global libraries stable so that old projects aren't altered by changes you made for a new one. For collaborative or long-lived work, link specific library states to project commits through version control instead of trusting a global environment that evolves on its own.
Make project libraries portable with KIPRJMOD
The single most useful setting in KiCad library management is the ${KIPRJMOD} path variable. It expands to the folder of the current project, so you can write library paths relative to it. The KiCad forum thread on relative paths for project libraries recommends placing project-specific libraries inside the project directory and using this variable in the library tables.
A clean layout looks like this:
my-board/
my-board.kicad_pro
my-board.kicad_sch
my-board.kicad_pcb
sym-lib-table
fp-lib-table
libs/
my-parts.kicad_sym
my-parts.pretty/
models/
The entries in sym-lib-table and fp-lib-table then point to ${KIPRJMOD}/libs/.... Because the path never mentions C:\Users\you or /home/you, the project opens the same way on Windows, macOS and Linux.
The project-contained rule
Forum regulars repeat one rule: any library a project needs should live inside the project folder. Whether it's a copy, a symlink or a submodule, the project is then pre-configured to find its libraries, with no per-user environment variables to set. Pick whichever mechanism suits your team, but keep the rule.
Use Git, but choose the mechanism deliberately
KiCad's files are text, so Git works well. The decisions are about how libraries relate to the project repository.
Option 1: copy libraries into the project
The simplest approach. Every commit contains the exact symbols and footprints the board used. The cost is duplication, and a fix to a shared part has to be copied to each project that needs it. For one-off boards and small teams, this is often the right answer.
Option 2: a separate library repository as a submodule
Long-standing forum advice is to keep libraries in a separate repository and include it as a submodule. The project then records exactly which library commit it was designed against. This is the pattern behind many tutorials on managing custom libraries with submodules.
It has a failure mode: if people edit files inside the submodule casually, you get messy local changes and merge conflicts. Two habits prevent this:
- Keep one approved, read-only master library for released parts. Designers pull from it but don't edit it directly.
- When someone does change a shared library, make small atomic commits, one part per commit, so conflicts stay small and reviewable.
Option 3: subtree
Git subtree brings the library history into your project repository, so there is no submodule pointer to forget to initialize. It suits teams that find submodules fiddly. The ${KIPRJMOD} approach works the same way.
Don't use a file-sync service as version control
A shared drive is not a version control system. As one forum reply puts it, cloud storage and version control are different things. Sync folders overwrite and conflict silently. If you must share through one, at least keep a Git repository as the source of truth.
Keep the cache library in version control
When you place symbols in a schematic, KiCad stores a copy of each one inside the schematic itself. In older projects this appears as a separate cache library file. Include it in your repository. It lets anyone open the project and see it as you left it, even when their global library setup differs from yours, which removes most "missing library" errors in hardware collaboration.
The cache is a safety net, not a replacement for libraries. If you want to update a part, you still edit the library symbol and then update the schematic from it. But when a reviewer, customer or contract manufacturer opens a file cold, the cache is why it looks right.
Upgrading KiCad without losing your libraries
Major version upgrades are where unmanaged libraries hurt. The installer gives you an option to import tables from the previous version, which the KiCad documentation presents as the recommended path if you manage custom libraries. It also offers to migrate the built-in libraries to the latest version.
On a fresh setup of a newer release, the KiCad 10 documentation offers a choice of how to initialize your symbol, footprint and design block libraries. If this is the first time you've set KiCad up, it suggests starting with the built-in libraries.
To migrate a design, KiCad's introduction says to open the project in the new version, then open the schematic and board and save each one. Do this on a branch, and commit the result separately from any design changes. If something looks off, you'll be able to tell whether the upgrade or your edit caused it.
If you contribute parts to KiCad's official libraries, there's a stricter rule: the library conventions require contributions to be made in the current stable version so changes in asset storage don't cause problems. It's a useful habit for your own shared libraries too: edit with the version the team is on, and upgrade deliberately.
Because custom assets that live in their own versioned library are isolated from KiCad's core library updates, a major KiCad update only touches the stock set. Your parts stay put.
A repeatable setup for a new project
Here is a sequence that works for a solo designer or a small hardware team.
- Create the project folder and initialize Git. Do it before the first part is placed.
- Create a
libsfolder inside it, with a symbol library file, a.prettyfootprint folder and a models folder. - Add the libraries to the project tables (not global) using
${KIPRJMOD}/libs/...paths. - Draw or import parts into the project libraries. Name symbols and footprints consistently, and keep the datasheet field filled in.
- Fill in the fields you'll need later: manufacturer, manufacturer part number, and package. These make the bill of materials usable.
- Commit the library tables, libraries and cache file along with the design.
- Test portability. Clone the repository into a fresh folder, ideally on another machine, and open it. If there are no errors, the setup works.
Step 7 takes five minutes and finds nearly every path problem.
Common problems and the fix
| Symptom | Likely cause | Fix |
|---|---|---|
| "No Symbol Library Detected" | Empty or missing global symbol table | Restore the default table or point to a valid sym-lib-table |
| Footprint not found after moving the project | Absolute path in a library table | Switch to ${KIPRJMOD} paths |
| Symbols look different on a colleague's machine | Their global library version differs | Commit the cache and project libraries |
| Parts changed after upgrading | Global libraries migrated underneath an old design | Pin libraries in the project and keep upgrades on a branch |
| Merge conflicts in shared libraries | Many people editing the same files | Read-only master library plus atomic commits |
Our perspective: libraries are half the job, sourcing is the other half
We build tools for people who design hardware and then have to buy it, so we see where library management meets purchasing. A library that is tidy but silent about the real world still leaves you guessing: is that footprint's part in stock, what does it cost at 100 pieces, and is there a second source?
Our advice is to put sourcing data into the library, not into a spreadsheet afterward. Fill manufacturer part number fields when you create a symbol. Then the bill of materials from your KiCad project can be matched to real parts without hand-editing, and a missing or end-of-life part shows up while changing the footprint is still cheap, not after boards are ordered.
We also think a library should be checked against the design it serves. That is why our Circuit Designer opens a KiCad project in the browser and shows the schematic, board and a priced BOM together. It reads the design the way a reviewer or buyer will, so it quickly exposes the gaps that a clean library on your own machine hides: missing fields, parts without a stable identity, footprints that don't match what was ordered. Design files stay in your browser unless you choose to save them to your account.
Most library trouble we see is not exotic. It's a path that only existed on one laptop, or a part with no part number. Fix those two and most of the pain goes away.
— Matthew
Check your libraries against real parts
Once your libraries are portable, test them against supply. Open the project in Circuit Designer to see the schematic, board and a BOM priced from the catalog. Or upload an export from KiCad, Altium or Eagle to the BOM tool to price the build at your quantity, with a recommended supplier for each line. The file is read in your browser and only part numbers are looked up. If a part is missing on your bench, Parts for Pickup maps nearby suppliers with a pickup counter.
A short checklist before you share a project
- Project library tables exist and use
${KIPRJMOD}paths. - No library path contains a username or drive letter.
- Cache file and library tables are committed.
- Every symbol has a manufacturer part number and a footprint assignment.
- The project opens cleanly from a fresh clone.
- The KiCad version used is noted in the README.
FAQ
Should I use global or project libraries in KiCad?
Use global libraries for KiCad's stock parts and project libraries for everything else. Global entries belong to your machine, so a design that depends on them won't open cleanly elsewhere. Project tables travel with the design.
Where does KiCad store its library tables?
Global tables are in your user configuration directory, for example ~/.config/kicad/9.0/ on Linux or %APPDATA%\kicad\9.0\ on Windows, per the KiCad documentation. Project tables sit in the project folder beside the design files.
How do I keep footprint libraries in sync across a team?
Keep an approved library in its own Git repository, pinned in each project through a submodule, subtree or copy, with a ${KIPRJMOD} path. Make it read-only for most designers and have changes reviewed in small commits. Every project then records the library state it was designed against.
Do I need to include the cache library in Git?
Yes. It lets anyone open the project and see it as you left it, even if their global libraries differ. It doesn't replace proper project libraries, but it prevents most missing-symbol problems when files are shared.
What happens to my custom libraries when I upgrade KiCad?
If you choose to import tables from the previous version during installation, your custom entries carry over, and you can migrate the built-in libraries at the same time. Libraries stored inside your project and under version control are unaffected by changes to the stock set.
Sources
- Getting Started in KiCad 9.0
- KiCad 10 documentation: libraries setup
- KiCad 10 documentation: introduction and migration
- KiCad library downloads
- KLC G1.8: contributions use the current stable version
- KiCad forum: relative paths for project libraries
- KiCad forum: kicad_common.json and portability
- KiCad forum: using Git to manage KiCad projects
- KiCad forum: version control with Google Drive