KiCad libraries are where a lot of new users get stuck — footprints go missing, a part looks right in the schematic but wrong on the board, or a project opens fine on one machine and breaks on another. Almost all of it comes down to understanding how KiCad organizes parts and where it looks for them.

Short answer: KiCad keeps symbols (schematic) and footprints (PCB) in separate libraries, linked per component, with 3D models attached to footprints. Two library tables — global and project — tell KiCad where those libraries live. Keep your libraries inside the project and reference them with relative paths, and your board stays reproducible anywhere.

How KiCad organizes symbols, footprints, and 3D models

KiCad deliberately splits a part into three layers, each stored differently:

Item What it is File / format Where it's used
Symbol Schematic representation — pins, names, electrical connections .kicad_sym (a symbol library holds many) Schematic editor (Eeschema)
Footprint Physical copper pads, silkscreen, courtyard the part solders to .pretty folder of .kicad_mod files PCB editor (Pcbnew)
3D model Visual solid for the 3D viewer and STEP export .step / .wrl, referenced by the footprint 3D viewer, mechanical export

The key idea: a symbol is not tied to a single footprint. When you place a resistor symbol, you separately assign which footprint it uses (0402, 0603, through-hole, and so on). This is what lets one symbol serve many physical packages. The footprint, in turn, points to a 3D model. Break that chain anywhere — symbol with no footprint, footprint with no 3D model — and only that layer is affected.

The global vs project library tables

KiCad finds libraries through two tables:

  • sym-lib-table — lists your symbol libraries.
  • fp-lib-table — lists your footprint libraries.

Each of these exists in two places:

  1. Global — in your KiCad configuration directory. These libraries are available in every project. KiCad ships its standard libraries here.
  2. Project — in the project folder, next to your .kicad_pro. These are available only in that project.

When you open a project, KiCad merges both tables. Every library has a nickname (like Device or MyParts), and parts are referenced as Nickname:PartName. If a global and project library share a nickname, the project one wins.

You rarely edit these files by hand. Use Preferences → Manage Symbol Libraries and Preferences → Manage Footprint Libraries — each dialog has a Global tab and a Project tab that map directly to the four files above.

Adding a third-party or manufacturer library

Many manufacturers and sites (like SnapEDA or component vendors) publish KiCad libraries. To add one:

  1. Download the library — typically a .kicad_sym file for symbols and a .pretty folder for footprints, sometimes with .step files for 3D.
  2. Open Manage Symbol Libraries, click the folder/add icon, point it at the .kicad_sym, and give it a nickname.
  3. Open Manage Footprint Libraries, add the .pretty folder the same way.
  4. If the footprints reference 3D models, drop those where the footprint expects them (often a path using the ${KIPRJMOD} project variable).

Decide deliberately whether to add it globally (reusable across all your projects) or to the project (travels with this board only). For a part you'll use everywhere, global is convenient. For a board you want to be self-contained and reproducible, project-level is the right call — more on that below.

Making your own symbol and footprint, and linking them

Sooner or later a part won't exist and you'll draw it yourself.

Symbol: Open the Symbol Editor, create or select a library to save into, add a new symbol, place pins with correct numbers and electrical types, and add the rectangle/body. Save it — it now lives in that .kicad_sym.

Footprint: Open the Footprint Editor, choose a .pretty library, create a new footprint, and place pads matching the datasheet's recommended land pattern. Set the courtyard and silkscreen. Save it into the .pretty folder.

Linking them: The two are joined when you assign the footprint to the symbol — either in the symbol's properties (the Footprint field) or later in the schematic via Tools → Assign Footprints. Optionally, in the footprint's properties, add a 3D model to complete the chain. Now placing your symbol and updating the PCB pulls in exactly the footprint you drew.

Keeping libraries versioned with the project

This is the difference between a board that rebuilds identically in two years and one that quietly rots. If your design depends on a global library on your laptop, nobody else — including future you — can reliably reproduce it.

The fix is to make the project self-contained:

  1. Put your custom .kicad_sym and .pretty folder inside the project directory.
  2. Add them to the project library tables (not global), using paths relative to ${KIPRJMOD} — the built-in variable for the project folder.
  3. Commit the symbol library, footprint folder, 3D models, and the .kicad_pro together.

Because KiCad files are plain text, this works beautifully with Git — see our guide on version control for KiCad projects for the full workflow. Anyone who clones the repo gets byte-identical libraries with zero setup.

Common pitfalls

  • Broken library paths. A library added by absolute path (/Users/you/parts/...) breaks the moment the project moves. Always prefer ${KIPRJMOD} relative paths for project libraries.
  • Missing footprints on another machine. Same root cause — the footprint lived in a global or custom-variable location that doesn't exist elsewhere. Store it in the project.
  • Nickname collisions. Two libraries with the same nickname: the project one shadows the global. Use distinct, descriptive nicknames.
  • Symbol updated but board unchanged. Editing a library symbol doesn't retroactively push into placed instances — use Tools → Update Symbols from Library in the schematic and Update PCB from Schematic.
  • 3D model not showing. The footprint's model path is unresolved. Check the path variable and that the .step/.wrl file is actually present.

Getting the electrical footprint right also matters downstream for sourcing — pairing footprints with the correct manufacturer part is covered in adding LCSC part numbers to your BOM.

Where GoForFab fits

Once your libraries are clean and committed with the project, generating manufacturing outputs should be automatic. GoForFab connects to a KiCad repository and, on every push, runs kicad-cli to regenerate the full package — Gerbers, BOM, CPL, DRC/ERC reports, and 3D renders — from the exact libraries committed alongside the board. No missing footprints, no "works on my machine." It's free forever to get started, so your reproducible project turns into reproducible outputs without any extra steps.