KiCadFiles documentation

A comprehensive Python library for parsing and manipulating KiCad file formats.

Features

Complete KiCad S-expression support: >200 classes representing KiCad tokens (missing tokens? create an issue with examples)
Type-safe parsing: Full Python type hints for all classes and methods
Flexible error handling: Three strictness modes (STRICT, FAILSAFE, SILENT)
Round-trip parsing: Parse KiCad files and convert back to S-expressions
Minimal dependencies: Self-contained S-expression parsing (no external dependencies)

Installation

pip install kicadfiles

Quick Start

Main File Format Classes

from kicadfiles import (
    KicadPcb, KicadSch, Footprint, KicadWks, KicadSymbolLib,
    KicadProject, KiCadDesignRules, FpLibTable, SymLibTable,
    ParseStrictness
)

# PCB board (.kicad_pcb)
pcb = KicadPcb.from_file("tests/fixtures/pcb/minimal.kicad_pcb", ParseStrictness.STRICT)
# pcb.save_to_file("output.kicad_pcb")  # Uncomment to save

# Schematic (.kicad_sch)
schematic = KicadSch.from_file("tests/fixtures/schematic/minimal.kicad_sch", ParseStrictness.STRICT)
# schematic.save_to_file("output.kicad_sch")  # Uncomment to save

# Footprint (.kicad_mod)
footprint = Footprint.from_file("tests/fixtures/footprints/small.kicad_mod", ParseStrictness.STRICT)
# footprint.save_to_file("output.kicad_mod")  # Uncomment to save

# Symbol library (.kicad_sym)
symbol_lib = KicadSymbolLib.from_file("tests/fixtures/symbols/small.kicad_sym", ParseStrictness.STRICT)
# symbol_lib.save_to_file("output.kicad_sym")  # Uncomment to save

# Worksheet (.kicad_wks)
worksheet = KicadWks.from_file("tests/fixtures/worksheets/small.kicad_wks", ParseStrictness.STRICT)
# worksheet.save_to_file("output.kicad_wks")  # Uncomment to save

# Project settings (.kicad_pro)
project = KicadProject.from_file("tests/fixtures/projects/minimal.kicad_pro", ParseStrictness.STRICT)
# project.save_to_file("output.kicad_pro")  # Uncomment to save

# Design rules (.kicad_dru)
design_rules = KiCadDesignRules.from_file("tests/fixtures/design_rules/minimal.kicad_dru", ParseStrictness.STRICT)
# design_rules.save_to_file("output.kicad_dru")  # Uncomment to save

# Footprint library table
fp_lib_table = FpLibTable.from_file("tests/fixtures/tables/fp-lib-table", ParseStrictness.STRICT)
# fp_lib_table.save_to_file("output-fp-lib-table")  # Uncomment to save

# Symbol library table
sym_lib_table = SymLibTable.from_file("tests/fixtures/tables/sym-lib-table", ParseStrictness.STRICT)
# sym_lib_table.save_to_file("output-sym-lib-table")  # Uncomment to save

Basic Usage

from kicadfiles import At, Layer, ParseStrictness

# Create objects using dataclass syntax
position = At(x=10.0, y=20.0, angle=90.0)
layer = Layer(name="F.Cu")

# Parse from S-expression
at_obj = At.from_sexpr("(at 10.0 20.0 90.0)", ParseStrictness.STRICT)

# Convert back to S-expression string
sexpr_str = at_obj.to_sexpr_str()
print(sexpr_str)  # Output: (at 10.0 20.0 90.0)

Parsing with Different Strictness Modes

from kicadfiles import At, ParseStrictness

# STRICT mode: Raises exceptions for any parsing errors
try:
    at_obj = At.from_sexpr("(at 10.0 20.0)", ParseStrictness.STRICT)
except ValueError as e:
    print(f"Parsing failed: {e}")

# FAILSAFE mode: Logs warnings and uses defaults for missing fields
at_obj = At.from_sexpr("(at 10.0 20.0)", ParseStrictness.FAILSAFE)
print(f"Angle defaulted to: {at_obj.angle}")  # Output: 0.0

# SILENT mode: Silently uses defaults for missing fields
at_obj = At.from_sexpr("(at 10.0 20.0)", ParseStrictness.SILENT)

Working with Complex Objects

from kicadfiles import Footprint, Pad, At, Size

# Create a footprint with pads
footprint = Footprint(
    library_link="Resistor_SMD:R_0603",
    at=At(x=50.0, y=30.0, angle=0.0),
    pads=[
        Pad(
            number="1",
            type="smd",
            shape="roundrect",
            at=At(x=-0.8, y=0.0),
            size=Size(width=0.7, height=0.9)
        ),
        Pad(
            number="2",
            type="smd",
            shape="roundrect",
            at=At(x=0.8, y=0.0),
            size=Size(width=0.7, height=0.9)
        )
    ]
)

# Convert to S-expression
sexpr = footprint.to_sexpr_str()
print(sexpr)

Contents:

Links:

Indices and tables