KiCad libraries explained: symbols, footprints and 3D models

How KiCad organises symbol, footprint and 3D model libraries, how to add your own or third-party libraries, and how to attach and align a 3D model on a footprint.

Every KiCad design draws on three kinds of library data: schematic symbols, PCB footprints and 3D models. They are stored separately and linked by name, which is flexible — but confusing the first time you try to add your own parts. Here is how the pieces fit together in current KiCad releases (7, 8 and 9).

The three library types

Type	Stored as	Used by
Symbol library	one `.kicad_sym` file holding many symbols	Schematic editor
Footprint library	a `.pretty` folder with one `.kicad_mod` file per footprint	PCB editor
3D model	`.step`/`.stp` or `.wrl` files, referenced from a footprint	3D viewer, STEP export, renders

A symbol carries a Footprint field such as Package_DIP:DIP-8_W7.62mm — the library nickname, a colon, then the footprint name. The footprint in turn lists one or more 3D model paths. Nothing is copied between them: if a nickname or a path doesn't resolve, you get a “footprint not found” error or an empty spot in the 3D view.

Library tables: global vs project

KiCad finds libraries through two tables, sym-lib-table and fp-lib-table. The global tables live in your KiCad configuration folder and apply to every project; project tables sit next to the .kicad_pro file and apply only there. Edit them from Preferences → Manage Symbol Libraries and Preferences → Manage Footprint Libraries.

Libraries you reuse everywhere — your personal parts, a vendor library — belong in the global table.
Parts made for one board belong in the project table, with paths built on ${KIPRJMOD} (the project folder). The project then stays portable: zip it, send it, and it opens on another computer with every part intact.

Path variables

Instead of absolute paths, KiCad uses variables set in Preferences → Configure Paths. The stock libraries are found through variables such as KICAD8_SYMBOL_DIR, KICAD8_FOOTPRINT_DIR and KICAD8_3DMODEL_DIR (the number follows the major version). Define your own — say MYLIB — and point 3D models at ${MYLIB}/3d/relay_sh.step. When the library folder moves, you change one variable instead of editing hundreds of footprints.

Adding a third-party library

Try the Plugin and Content Manager first (in the KiCad project window). Many community libraries install from there with one click and register themselves in the tables.
For a downloaded library, copy it somewhere permanent, then add the .kicad_sym file to the symbol table and the .pretty folder to the footprint table, each under a short, unique nickname.
Older libraries in the legacy .lib (symbols) and .mod (footprints) formats can usually still be added. It's worth converting them to the current formats so you're not relying on legacy loaders — KiCad offers to migrate old symbol libraries, and footprints can be saved into a fresh .pretty library from the Footprint Editor.
Coming from Eagle? KiCad can read Eagle .lbr files directly — see moving from Eagle to KiCad.

Attaching a 3D model to a footprint

Open the footprint in the Footprint Editor and go to Footprint Properties → 3D Models.
Add a model file. STEP is best for mechanical work (checking the board in an enclosure); WRL (VRML) can carry colours and materials, so it often looks better in renders.
Adjust offset, rotation and scale until the model sits on the pads — the preview updates live. Models from different sources frequently need a 90° turn or a Z offset.
You can stack several models on one footprint: an IC plus its socket, or a connector plus the mating plug. Give the upper one a Z offset equal to the height of the one below.

Tip: resistors and electrolytic capacitors look far more realistic with value-specific models — one WRL per value with the right colour bands or sleeve colour. Keep them in their own folder and swap the model path in the placed footprint when you want a photo-realistic render.

Keeping libraries healthy

Never edit the stock libraries in place — updates overwrite them. Copy the part into your own library first, then change it.
Name footprints after the package and pitch (SOIC-8_3.9x4.9mm_P1.27mm) rather than a part number, so one footprint serves many parts.
Run the built-in checkers (Inspect menu in the Symbol and Footprint editors) on every new part.
Check a new footprint against the datasheet's recommended land pattern, then print the PCB at 1:1 and lay the real part on the paper. It's the cheapest way to catch a wrong pitch before you order boards.