File Formats

Overview

KiCad uses S-expression (symbolic expression) based file formats for all native files. This provides:

Human-readable text format
Version control friendly (meaningful diffs)
Extensible structure
Forward and backward compatibility
Fast parsing performance

S-Expression Format

Syntax

S-expressions are nested lists enclosed in parentheses:

(token value)
(parent
  (child1 value1)
  (child2 value2 value3)
)

Parser

Implementation: libs/sexpr/ Features:

Recursive descent parsing
Streaming support for large files
Line number tracking for errors
UTF-8 support

Example:

#include <sexpr/sexpr.h>

SEXPR::SEXPR* expr = SEXPR::PARSER::ParseFromFile("file.kicad_pcb");

Native File Formats

Schematic Files (`.kicad_sch`)

Purpose: Store schematic design data Structure:

(kicad_sch
  (version 20250610)
  (generator "eeschema")
  (generator_version "9.99")
  (uuid "1b112ac5-701b-420f-be34-0e29a2cb55ca")
  
  (paper "A3")
  (title_block
    (title "My Design")
    (date "2025-03-05")
    (rev "1.0")
    (company "ACME Corp")
  )
  
  (lib_symbols
    (symbol "Device:R"
      (property "Reference" "R"
        (at 0 0 0)
        (effects (font (size 1.27 1.27)))
      )
      (property "Value" "R"
        (at 0 -2.54 0)
        (effects (font (size 1.27 1.27)))
      )
      (symbol "R_0_1"
        (rectangle (start -1.016 2.54) (end 1.016 -2.54)
          (stroke (width 0.254)) (fill (type none))
        )
      )
    )
  )
  
  (symbol
    (lib_id "Device:R")
    (at 100 100 0)
    (uuid "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d")
    (property "Reference" "R1" (at 102.87 98.7714 0))
    (property "Value" "10k" (at 102.87 101.2714 0))
    (pin "1" (uuid "abc123"))
    (pin "2" (uuid "def456"))
  )
  
  (wire (pts (xy 95.25 100) (xy 100 100))
    (stroke (width 0) (type default))
    (uuid "wire-uuid-1")
  )
)

Key sections:

Header: Version, generator, UUID
Page setup: Paper size, title block
Symbol libraries: Embedded symbol definitions
Instances: Placed symbols with properties
Wiring: Net connections
Annotations: Text, labels, notes
Hierarchical sheets: Sub-schematics

Properties:

Reference - Component reference (R1, C5, etc.)
Value - Component value
Footprint - Associated PCB footprint
Datasheet - Documentation URL
Custom fields - User-defined properties

PCB Files (`.kicad_pcb`)

Purpose: Store printed circuit board layout Structure:

(kicad_pcb
  (version 20250610)
  (generator "pcbnew")
  (generator_version "9.99")
  
  (general
    (thickness 1.6)
    (legacy_teardrops no)
  )
  
  (paper "A4")
  
  (layers
    (0 "F.Cu" signal)
    (31 "B.Cu" signal)
    (32 "B.Adhes" user "B.Adhesive")
    (33 "F.Adhes" user "F.Adhesive")
    (34 "B.Paste" user)
    (35 "F.Paste" user)
    (36 "B.SilkS" user "B.Silkscreen")
    (37 "F.SilkS" user "F.Silkscreen")
    (38 "B.Mask" user)
    (39 "F.Mask" user)
    (40 "Dwgs.User" user "User.Drawings")
    (41 "Cmts.User" user "User.Comments")
    (42 "Eco1.User" user "User.Eco1")
    (43 "Eco2.User" user "User.Eco2")
    (44 "Edge.Cuts" user)
    (45 "Margin" user)
  )
  
  (setup
    (pad_to_mask_clearance 0)
    (allow_soldermask_bridges_in_footprints no)
    (pcbplotparams
      (layerselection 0x00010fc_ffffffff)
      (plot_on_all_layers_selection 0x0000000_00000000)
      (disableapertmacros no)
      (usegerberextensions yes)
    )
  )
  
  (net 0 "")
  (net 1 "GND")
  (net 2 "+3V3")
  (net 3 "Net-(R1-Pad2)")
  
  (footprint "Resistor_SMD:R_0603_1608Metric"
    (layer "F.Cu")
    (uuid "footprint-uuid")
    (at 150 100)
    (descr "Resistor SMD 0603")
    (tags "resistor")
    (property "Reference" "R1"
      (at 0 -1.43 0)
      (layer "F.SilkS")
      (uuid "ref-uuid")
      (effects (font (size 1 1) (thickness 0.15)))
    )
    (property "Value" "10k"
      (at 0 1.43 0)
      (layer "F.Fab")
      (uuid "val-uuid")
      (effects (font (size 1 1) (thickness 0.15)))
    )
    (fp_line (start -0.237258 -0.5225) (end 0.237258 -0.5225)
      (stroke (width 0.12) (type solid))
      (layer "F.SilkS")
      (uuid "line-uuid")
    )
    (pad "1" smd roundrect (at -0.825 0) (size 0.8 0.95)
      (layers "F.Cu" "F.Paste" "F.Mask")
      (roundrect_rratio 0.25)
      (net 2 "+3V3")
      (uuid "pad1-uuid")
    )
    (pad "2" smd roundrect (at 0.825 0) (size 0.8 0.95)
      (layers "F.Cu" "F.Paste" "F.Mask")
      (roundrect_rratio 0.25)
      (net 3 "Net-(R1-Pad2)")
      (uuid "pad2-uuid")
    )
  )
  
  (segment (start 149.175 100) (end 148 100)
    (width 0.25)
    (layer "F.Cu")
    (net 2)
    (uuid "seg-uuid")
  )
  
  (zone (net 1) (net_name "GND") (layer "F.Cu")
    (uuid "zone-uuid")
    (hatch edge 0.5)
    (connect_pads (clearance 0.5))
    (min_thickness 0.25)
    (filled_areas_thickness no)
    (fill yes (thermal_gap 0.5) (thermal_bridge_width 0.5))
    (polygon
      (pts
        (xy 130 90)
        (xy 170 90)
        (xy 170 110)
        (xy 130 110)
      )
    )
  )
)

Key sections:

Header: Version, generator
General: Board properties (thickness, etc.)
Layers: Layer stack definition
Setup: Manufacturing parameters
Nets: Electrical connectivity
Footprints: Component placements
Tracks/Vias: Copper routing
Zones: Copper pours
Drawings: Silkscreen, fabrication layers

Symbol Libraries (`.kicad_sym`)

Purpose: Reusable schematic symbol definitions Structure:

(kicad_symbol_lib
  (version 20250610)
  (generator "kicad_symbol_editor")
  
  (symbol "Resistor"
    (pin_numbers hide)
    (pin_names (offset 0))
    (exclude_from_sim no)
    (in_bom yes)
    (on_board yes)
    
    (property "Reference" "R"
      (at 2.032 0 90)
      (effects (font (size 1.27 1.27)))
    )
    (property "Value" "Resistor"
      (at -2.032 0 90)
      (effects (font (size 1.27 1.27)))
    )
    (property "Footprint" ""
      (at 0 0 0)
      (effects (font (size 1.27 1.27)) hide)
    )
    
    (symbol "Resistor_0_1"
      (rectangle (start -1.016 2.54) (end 1.016 -2.54)
        (stroke (width 0.254) (type default))
        (fill (type none))
      )
    )
    
    (symbol "Resistor_1_1"
      (pin passive line (at 0 3.81 270)
        (length 1.27)
        (name "~" (effects (font (size 1.27 1.27))))
        (number "1" (effects (font (size 1.27 1.27))))
      )
      (pin passive line (at 0 -3.81 90)
        (length 1.27)
        (name "~" (effects (font (size 1.27 1.27))))
        (number "2" (effects (font (size 1.27 1.27))))
      )
    )
  )
)

Symbol units:

_0_1 - Graphical representation (body)
_1_1 - First unit pins
_2_1 - Second unit pins (for multi-unit symbols)

Pin types:

input - Input pin
output - Output pin
bidirectional - Bidirectional I/O
tri_state - Tri-state output
passive - Passive component
power_in - Power input
power_out - Power output
open_collector - Open collector
open_emitter - Open emitter
unspecified - Unspecified

Footprint Libraries (`.kicad_mod`)

Purpose: PCB footprint definitions Structure:

(footprint "R_0603_1608Metric"
  (version 20250610)
  (generator "pcbnew")
  (generator_version "9.99")
  (layer "F.Cu")
  
  (descr "Resistor SMD 0603 (1608 Metric)")
  (tags "resistor")
  
  (property "Reference" "REF**"
    (at 0 -1.43 0)
    (layer "F.SilkS")
    (uuid "ref-uuid")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  
  (property "Value" "R_0603_1608Metric"
    (at 0 1.43 0)
    (layer "F.Fab")
    (uuid "val-uuid")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  
  (property "Footprint" ""
    (at 0 0 0)
    (unlocked yes)
    (layer "F.Fab")
    (hide yes)
    (uuid "fp-uuid")
    (effects (font (size 1.27 1.27)))
  )
  
  (attr smd)
  
  (fp_line (start -0.237258 -0.5225) (end 0.237258 -0.5225)
    (stroke (width 0.12) (type solid))
    (layer "F.SilkS")
    (uuid "line1-uuid")
  )
  
  (fp_line (start -0.237258 0.5225) (end 0.237258 0.5225)
    (stroke (width 0.12) (type solid))
    (layer "F.SilkS")
    (uuid "line2-uuid")
  )
  
  (fp_rect (start -0.8 -0.4) (end 0.8 0.4)
    (stroke (width 0.1) (type solid))
    (fill none)
    (layer "F.Fab")
    (uuid "rect-uuid")
  )
  
  (fp_text user "${REFERENCE}"
    (at 0 0 0)
    (layer "F.Fab")
    (uuid "text-uuid")
    (effects (font (size 0.4 0.4) (thickness 0.06)))
  )
  
  (pad "1" smd roundrect (at -0.825 0)
    (size 0.8 0.95)
    (layers "F.Cu" "F.Paste" "F.Mask")
    (roundrect_rratio 0.25)
    (uuid "pad1-uuid")
  )
  
  (pad "2" smd roundrect (at 0.825 0)
    (size 0.8 0.95)
    (layers "F.Cu" "F.Paste" "F.Mask")
    (roundrect_rratio 0.25)
    (uuid "pad2-uuid")
  )
  
  (model "${KICAD8_3DMODEL_DIR}/Resistor_SMD.3dshapes/R_0603_1608Metric.wrl"
    (offset (xyz 0 0 0))
    (scale (xyz 1 1 1))
    (rotate (xyz 0 0 0))
  )
)

Layers:

F.Cu/B.Cu: Copper (front/back)
F.SilkS/B.SilkS: Silkscreen
F.Mask/B.Mask: Solder mask
F.Paste/B.Paste: Solder paste (stencil)
F.Fab/B.Fab: Fabrication layer
Dwgs.User: User drawings
Cmts.User: Comments
Edge.Cuts: Board outline

Pad types:

thru_hole - Plated through-hole
smd - Surface mount
connect - Connection point (no copper)
np_thru_hole - Non-plated hole

Pad shapes:

circle - Circular
rect - Rectangular
oval - Oval
trapezoid - Trapezoidal
roundrect - Rounded rectangle
custom - Custom shape polygon

Project Files (`.kicad_pro`)

Purpose: Project settings and metadata Format: JSON (exception to S-expression) Structure:

{
  "board": {
    "design_settings": {
      "defaults": {
        "board_outline_line_width": 0.15,
        "copper_line_width": 0.2,
        "copper_text_size_h": 1.5,
        "copper_text_size_v": 1.5
      },
      "diff_pair_dimensions": [],
      "drc_exclusions": [],
      "rules": {
        "min_copper_edge_clearance": 0.5,
        "solder_mask_clearance": 0.0,
        "solder_mask_min_width": 0.0
      },
      "track_widths": [0.25, 0.3, 0.5, 1.0],
      "via_dimensions": [
        {"diameter": 0.8, "drill": 0.4}
      ]
    },
    "layer_presets": [],
    "viewports": []
  },
  "boards": [],
  "cvpcb": {
    "equivalence_files": []
  },
  "erc": {
    "erc_exclusions": [],
    "meta": {"version": 0},
    "pin_map": [[0, 0, 0], [0, 2, 1]],
    "rule_severities": {}
  },
  "libraries": {
    "pinned_footprint_libs": [],
    "pinned_symbol_libs": []
  },
  "meta": {
    "filename": "project.kicad_pro",
    "version": 1
  },
  "net_settings": {
    "classes": [
      {
        "bus_width": 12,
        "clearance": 0.2,
        "diff_pair_gap": 0.25,
        "diff_pair_via_gap": 0.25,
        "diff_pair_width": 0.2,
        "line_style": 0,
        "microvia_diameter": 0.3,
        "microvia_drill": 0.1,
        "name": "Default",
        "pcb_color": "rgba(0, 0, 0, 0.000)",
        "schematic_color": "rgba(0, 0, 0, 0.000)",
        "track_width": 0.25,
        "via_diameter": 0.8,
        "via_drill": 0.4,
        "wire_width": 6
      }
    ],
    "meta": {"version": 3},
    "net_colors": null,
    "netclass_assignments": null,
    "netclass_patterns": []
  },
  "pcbnew": {
    "last_paths": {
      "gencad": "",
      "idf": "",
      "netlist": "",
      "plot": "",
      "pos_files": "",
      "specctra_dsn": "",
      "step": "",
      "svg": "",
      "vrml": ""
    },
    "page_layout_descr_file": ""
  },
  "schematic": {
    "legacy_lib_dir": "",
    "legacy_lib_list": []
  },
  "sheets": [
    ["root-uuid", "Root Sheet"]
  ],
  "text_variables": {}
}

Library Tables

Symbol Library Table (`sym-lib-table`)

Purpose: Define symbol library locations Format: S-expression

(sym_lib_table
  (version 7)
  (lib (name "Device")(type "KiCad")(uri "${KICAD8_SYMBOL_DIR}/Device.kicad_sym")(options "")(descr "Basic devices"))
  (lib (name "Connector")(type "KiCad")(uri "${KICAD8_SYMBOL_DIR}/Connector.kicad_sym")(options "")(descr "Connectors"))
  (lib (name "Custom")(type "KiCad")(uri "${KIPRJMOD}/libs/custom.kicad_sym")(options "")(descr "Project-specific symbols"))
)

Scope:

Global: ~/.config/kicad/8.0/sym-lib-table
Project: project/sym-lib-table

Footprint Library Table (`fp-lib-table`)

Purpose: Define footprint library locations

(fp_lib_table
  (version 7)
  (lib (name "Resistor_SMD")(type "KiCad")(uri "${KICAD8_FOOTPRINT_DIR}/Resistor_SMD.pretty")(options "")(descr "SMD resistors"))
  (lib (name "Connector_PinHeader_2.54mm")(type "KiCad")(uri "${KICAD8_FOOTPRINT_DIR}/Connector_PinHeader_2.54mm.pretty")(options "")(descr "2.54mm pin headers"))
)

Library types:

KiCad - Native .pretty directories
GitHub - Remote GitHub repositories
Legacy - Old .mod format

Auxiliary File Formats

Design Rules (`*.kicad_dru`)

Purpose: Custom design rule definitions Format: S-expression

Worksheets (`.kicad_wks`)

Purpose: Drawing sheet/title block templates Format: S-expression Elements:

Lines, rectangles, polygons
Text with variable substitution
Images/logos
Page numbering

3D Model Files

Supported formats:

STEP (.step, .stp) - Industry standard CAD
VRML (.wrl) - 3D mesh format
X3D (.x3d) - XML-based 3D

Model locations:

Environment variable: ${KICAD8_3DMODEL_DIR}
Project relative: ${KIPRJMOD}/3d_models/

Export Formats

Manufacturing Outputs

Gerber (RS-274X)

Extension: .gbr, .gtl, .gbl, etc. Layers:

.gtl - Top copper (F.Cu)
.gbl - Bottom copper (B.Cu)
.gto - Top silkscreen (F.SilkS)
.gbo - Bottom silkscreen (B.SilkS)
.gts - Top solder mask (F.Mask)
.gbs - Bottom solder mask (B.Mask)
.gm1 - Board outline (Edge.Cuts)

Drill files:

Excellon format (.drl)
Separate PTH/NPTH or merged

Pick-and-Place

Extension: .pos Format: CSV

Ref,Val,Package,PosX,PosY,Rot,Side
R1,10k,R_0603_1608Metric,150.00,100.00,0,top
C1,100nF,C_0603_1608Metric,155.00,100.00,90,top

Bill of Materials (BOM)

Extension: .csv, .xml Formats:

CSV - Simple tabular
XML - Structured data
Custom via BOM plugins

Documentation

PDF

Purpose: Printable schematics and PCB layouts Features:

Vector graphics
Embedded fonts
Color/monochrome
Layer selection

SVG

Purpose: Web-friendly vector graphics Use cases:

Documentation websites
Interactive viewers
Editing in vector tools

CAD Exchange

DXF (Drawing Exchange Format)

Purpose: Mechanical CAD integration Exported data:

Board outline
Component outlines
Mounting holes
Keepout zones

STEP (`.step`)

Purpose: 3D mechanical model Content:

Board substrate
Component 3D models
Accurate positioning
Assembly validation

IDF (Intermediate Data Format)

Purpose: MCAD ↔ ECAD exchange Files:

.emn - Board outline and components
.emp - Component library

Versions: IDF 2.0, 3.0, 4.0

File Format Versioning

Version Field

All KiCad files include version number:

(kicad_pcb
  (version 20250610)  ; YYYYMMDD format
  ...
)

Compatibility

Forward compatibility: Newer KiCad versions can open older files Backward compatibility: Limited - older versions may not understand new features Migration: Automatic format upgrade on save

Version History

20250610: KiCad 9.0 development
20231231: KiCad 8.0 release
20230620: KiCad 7.0 release
20211014: KiCad 6.0 release
20200825: KiCad 5.99 (development)

File Encoding

Character encoding: UTF-8 (mandatory) Line endings:

Unix: LF (\n)
Windows: CRLF (\r\n) - normalized to LF
macOS: LF (\n)

Whitespace: Flexible (spaces/tabs for formatting)

File Compression

Native files are not compressed to ensure:

Version control efficiency (meaningful diffs)
Text editor compatibility
Debugging capability
Cross-platform portability

For archival, use standard compression (ZIP, tar.gz).

Contributing

Architecture

API Reference

​Overview

​S-Expression Format

​Syntax

​Parser

​Native File Formats

​Schematic Files (.kicad_sch)

​PCB Files (.kicad_pcb)

​Symbol Libraries (.kicad_sym)

​Footprint Libraries (.kicad_mod)

​Project Files (.kicad_pro)

​Library Tables

​Symbol Library Table (sym-lib-table)

​Footprint Library Table (fp-lib-table)

​Auxiliary File Formats

​Design Rules (*.kicad_dru)

​Worksheets (.kicad_wks)

​3D Model Files

​Export Formats

​Manufacturing Outputs

​Gerber (RS-274X)

​Pick-and-Place

​Bill of Materials (BOM)

​Documentation

​PDF

​SVG

​CAD Exchange

​DXF (Drawing Exchange Format)

​STEP (.step)

​IDF (Intermediate Data Format)

​File Format Versioning

​Version Field

​Compatibility

​Version History

​File Encoding

​File Compression

​See Also

Build docs developers (and LLMs) love