How Do You Create and Manage KiCad Footprint and Symbol Libraries?

Detailed Explanation

KiCad manages schematic symbols and PCB footprints in separate library systems, each with its own editor and file format. This separation is intentional: a single resistor symbol covers every physical package, and the footprint choice is an independent layout-stage decision. The practical implication is that both assets must be correct and consistent — a mismatch between symbol pin numbers and footprint pad numbers produces wrong connections on the assembled board.

KiCad ships with an extensive official library covering thousands of standard parts. Engineers need custom library entries for proprietary connectors, company-specific component variants, parts released after the library was last updated, and package variants not yet in the official collection.

For a conceptual explanation of how symbols and footprints relate to each other, see PCB Footprint vs Schematic Symbol: What Is the Difference?.

KiCad Library File Formats

KiCad 6 introduced the .kicad_sym format, replacing the older .lib + .dcm pair from KiCad 5. KiCad 8 can open (but not write back to) legacy .lib files — for any new library work, create .kicad_sym files. All formats are plain text, making them diff-friendly for version control.

The Library Table

KiCad discovers libraries through two library tables — one for symbols, one for footprints:

• Global table — stored in the KiCad user configuration directory (on Windows: %APPDATA%\kicad\8.0\sym-lib-table and fp-lib-table; on macOS/Linux: ~/.config/kicad/8.0/). Lists libraries available in every KiCad project on that machine.
• Project table — a sym-lib-table and fp-lib-table placed inside the project folder, adding libraries scoped to that project only.

Add and manage library table entries via Preferences → Manage Symbol Libraries (in the Schematic Editor or Symbol Editor) and Preferences → Manage Footprint Libraries (in the PCB Editor or Footprint Editor). Each entry has a Nickname (the identifier used in symbol/footprint references) and a Library Path.

Project-scoped libraries keep each design self-contained: when you hand a project folder to a colleague or fabrication house, all custom parts travel with it.

Creating a Custom Symbol

Open the Symbol Editor via the Symbol Editor button in the KiCad project manager, or via Tools → Symbol Editor from the Schematic Editor.

1. Create or open a library. Go to File → New Library to create a new .kicad_sym file, then choose whether to add it to the global or project table. Alternatively, right-click an existing library in the left panel tree and select New Symbol to add to that library.

2. Set symbol properties. When creating a new symbol, set:

• Symbol name — use the manufacturer part number for IC-specific symbols (e.g. STM32G030K8T6), or a generic descriptor for passives
• Reference designator prefix — U for ICs, J for connectors, R for resistors, C for capacitors, Q for transistors
• Default value — displayed as the value or part number on the schematic

3. Draw the body. Use the Add Rectangle tool to draw the symbol's body outline. KiCad symbols use a 100 mil (2.54 mm) grid — pins placed on this grid connect cleanly to schematic wires.

4. Add pins. Press P to place each pin. For every pin, set:

• Pin number — must match the physical pin number in the datasheet exactly; this number ties the symbol pin to the footprint pad via the netlist, so an error here silently assigns the wrong net to the wrong copper pad
• Pin name — the signal name from the datasheet (e.g. PA0, NRST, VDD)
• Electrical type — Input, Output, Bidirectional, Power Input, Power Output, Passive, No Connect, Open Collector, etc.; ERC uses these types to detect conflicting drivers on a net and undriven inputs
• Pin length — 100 mil is standard; place pin endpoints on the 100 mil grid so wires snap correctly

5. Multi-unit symbols. For ICs with repeated functional blocks (quad op-amp, dual comparator), use multi-unit symbols: each unit represents one functional block of the IC but they share a single BOM entry. Set the unit count in symbol properties when creating the symbol.

6. Save. Press Ctrl+S to save to the library file.

Creating a Custom Footprint

Open the Footprint Editor via the Footprint Editor button in the KiCad project manager, or via Tools → Footprint Editor from the PCB Editor.

1. Create or open a footprint library. Go to File → New Library to create a new .pretty directory, then add it to the footprint library table.

2. Locate the reference dimensions. Before drawing pads, identify:

• The component datasheet's Recommended PCB Land Pattern section (preferred) — pad dimensions derived by the manufacturer for solder fillet formation
• The package drawing — physical body and lead dimensions if no recommended land pattern is provided
• IPC-7351 (stable standard) — for SMD packages without a datasheet land pattern, the standard defines three density classes: Maximum (Class B), Nominal (Class M), and Minimum (Class C); KiCad's official library uses Nominal density

3. Add pads. Press O to place each pad. Key pad properties:

• Pad number — must match the symbol pin number for the same physical connection; the netlist links these
• Pad type — SMD (copper on one side), Through-hole (plated, connecting front and back copper), or NPTH (non-plated mechanical hole)
• Size — copper pad dimensions from the recommended land pattern
• Layer assignment — SMD pads typically use F.Cu + F.Paste + F.Mask together

Thermal / exposed pads. QFN, DFN, and similar packages have a large central exposed pad (EP) for thermal dissipation. Create this as a standard SMD pad with the correct dimensions. To control solder paste volume and reduce voiding under the pad, the stencil aperture should typically be subdivided into a grid of smaller apertures — commonly 25–50% paste coverage of the total pad area, with individual apertures no larger than approximately 1.5 mm × 1.5 mm (per IPC-7525 solder paste stencil design guidelines, though exact sizing depends on paste type and assembly process). Set aperture overrides in the pad's Paste/Mask Overrides properties.

4. Add the courtyard. Draw a closed shape on F.Courtyard around the complete component, extending typically 0.25–0.5 mm beyond the package outline. DRC flags courtyard overlaps between adjacent components. A footprint without a courtyard silently skips all courtyard-related DRC checks.

5. Add silkscreen and fabrication layers. Add the package body outline to F.Fab (the assembly drawing layer visible to the pick-and-place operator) and the component reference outline to F.SilkS. Silkscreen lines must not overlap copper pads — KiCad DRC flags this as a solder joint risk.

6. Assign a 3D model. In footprint properties, add a path to a .step or .wrl 3D model. Use ${KICAD8_3DMODEL_DIR} for models from the KiCad official 3D library, or ${KIPRJMOD} for project-local models. A 3D model enables component clearance checking in View → 3D Viewer during board layout.

7. Save. Press Ctrl+S to save the footprint file to the .pretty library directory.

Version Control for KiCad Libraries

KiCad's plain-text library files produce meaningful diffs in Git, making version control practical.

Include in Git:

project-libs.kicad_sym          # custom symbol library
project-libs.pretty/            # custom footprint library directory
project-libs.pretty/*.kicad_mod # individual footprint files
sym-lib-table                   # project symbol library table
fp-lib-table                    # project footprint library table

Add to .gitignore (KiCad auto-generated files that must not be committed):

fp-info-cache
*.kicad_prl
*.lck

The fp-info-cache file regenerates automatically whenever KiCad scans footprint libraries and produces large, noisy diffs with no useful content — always exclude it. .lck files appear only while KiCad has a file open and must never be committed.

Team library pattern. A common approach for teams or multi-project organisations is a dedicated company-kicad-libs Git repository containing both .kicad_sym files and .pretty directories. Individual projects include it as a Git submodule and reference it via the project-level sym-lib-table and fp-lib-table. This gives every project access to the same verified library while keeping library history and project history independent.

Design Considerations

• Derive footprint pad dimensions from the recommended land pattern, not the package body. The package body drawing shows the physical component outline; the recommended land pattern gives the correct copper pad sizes for reliable solder joint formation. These differ — package lead dimensions do not account for solder fillet extension beyond the lead, and using body dimensions to set pad size typically produces undersized pads.
• Pin number agreement between symbol and footprint is mandatory. Symbol pin 1 connects to footprint pad 1 via the netlist. A mismatch silently crosses two signals at the PCB level. ERC cannot detect this (it operates on symbols only); DRC cannot detect it (it operates on footprints only). The mismatch only surfaces when the assembled board is powered up.
• Keep project-specific parts in project-scoped libraries. A growing global library becomes difficult to maintain and may contain outdated or superseded parts. Project-scoped libraries keep each design self-contained and prevent global library changes from silently affecting past projects.
• Back up custom library files before major KiCad version upgrades. KiCad has migrated its library format between major versions. Library files not tracked in version control can be lost if a format migration behaves unexpectedly.
• For designs with many proprietary or custom components where incorrect land patterns could cause assembly failures, Zeus Design's PCB design service handles full component library build-out as part of the design engagement, including IPC-7351-compliant land pattern derivation.

Common Mistakes

• Pin number mismatch between symbol and footprint. The most consequential library error — it silently crosses signals. Verify pin numbering against the datasheet immediately after creating a symbol and its paired footprint, and re-check when adapting an existing symbol for a new package variant.
• Building footprint pads from package body dimensions instead of the recommended land pattern. Package body dimensions describe where the component sits on the board. The recommended land pattern describes where the solder joints form. Using body dimensions typically produces undersized pads that fail inspection or cause poor solder joint formation.
• Missing courtyard boundary. KiCad skips courtyard overlap and clearance DRC checks for footprints without a courtyard. A footprint missing its courtyard can be placed so close to an adjacent component that pick-and-place equipment cannot seat it, or that the courtyard overlap would have caught a spacing violation.
• Creating a library file without registering it in the library table. Creating a .kicad_sym file or .pretty directory does not automatically make it visible to KiCad's editors. The file must be added to the symbol or footprint library table via Preferences → Manage Libraries before it appears in the chooser.
• Relying on KiCad's auto-import of legacy .lib files for ongoing work. KiCad 8 can open .lib files, but saving triggers a conversion to .kicad_sym. If the original .lib file is in version control but the converted file is not committed, the converted version exists only on the local machine and is invisible to teammates or after a clean checkout.
• Not subdividing the thermal pad stencil aperture. A single large paste aperture over a QFN exposed pad deposits excess solder paste, which can lift the component body during reflow. Set per-pad paste aperture overrides in the footprint editor rather than relying on the stencil supplier to subdivide the aperture after the fact.