kicad-file-format

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KiCad File Format Reference

KiCad 文件格式参考手册

Complete reference for KiCad 8.x S-expression file formats.

KiCad uses Lisp-style S-expressions for all file formats. Files are human-readable and text-based.

KiCad 8.x 版本S表达式文件格式的完整参考手册。

KiCad 的所有文件格式均采用类Lisp风格的S表达式。文件为人类可读的纯文本格式。

1. S-Expression Basics

1. S表达式基础

Syntax

语法

lisp

(keyword value)
(keyword (nested value))
(keyword
  (child1 value)
  (child2 value)
)

lisp

(keyword value)
(keyword (nested value))
(keyword
  (child1 value)
  (child2 value)
)

Common Patterns

通用模式

Coordinates:
```
(at x y angle)
```
or
```
(xy x y)
```

UUIDs:

(uuid "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

Strings:
```
"quoted string"
```
or
```
unquoted_identifier
```
Numbers:
```
1.234
```
(always decimal, no units in file)
Booleans:
```
yes
```
/
```
no
```

坐标：
```
(at x y angle)
```
或
```
(xy x y)
```

UUID：

(uuid "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

字符串：
```
"quoted string"
```
或
```
unquoted_identifier
```
数字：
```
1.234
```
（始终为十进制，文件中不包含单位）
布尔值：
```
yes
```
/
```
no
```

2. Schematic Format (.kicad_sch)

2. 原理图格式（.kicad_sch）

File Structure

文件结构

lisp

(kicad_sch
  (version 20231120)
  (generator "eeschema")
  (generator_version "8.0")
  (uuid "project-uuid")
  (paper "A4")
  
  ; Title block
  (title_block
    (title "Project Title")
    (date "2024-01-01")
    (rev "1.0")
    (company "Company Name")
  )
  
  ; Library symbols (embedded copies)
  (lib_symbols
    (symbol "Device:R" ...)
  )
  
  ; Placed symbols (component instances)
  (symbol ...)
  (symbol ...)
  
  ; Wires and connections
  (wire ...)
  (bus ...)
  (junction ...)
  
  ; Labels and nets
  (label ...)
  (global_label ...)
  (hierarchical_label ...)
  
  ; Hierarchical sheets
  (sheet ...)
  
  ; Text and graphics
  (text ...)
  (polyline ...)
  (rectangle ...)
)

lisp

(kicad_sch
  (version 20231120)
  (generator "eeschema")
  (generator_version "8.0")
  (uuid "project-uuid")
  (paper "A4")
  
  ; 标题栏
  (title_block
    (title "Project Title")
    (date "2024-01-01")
    (rev "1.0")
    (company "Company Name")
  )
  
  ; 库符号（嵌入式副本）
  (lib_symbols
    (symbol "Device:R" ...)
  )
  
  ; 放置的符号（元件实例）
  (symbol ...)
  (symbol ...)
  
  ; 导线与连接
  (wire ...)
  (bus ...)
  (junction ...)
  
  ; 标签与网络
  (label ...)
  (global_label ...)
  (hierarchical_label ...)
  
  ; 层次化原理图页
  (sheet ...)
  
  ; 文本与图形
  (text ...)
  (polyline ...)
  (rectangle ...)
)

Symbol Instance

符号实例

lisp

(symbol
  (lib_id "Device:R")
  (at 100 50 0)              ; x, y, rotation (0, 90, 180, 270)
  (unit 1)                   ; Multi-unit symbols
  (exclude_from_sim no)
  (in_bom yes)
  (on_board yes)
  (dnp no)                   ; Do Not Populate
  (uuid "symbol-uuid")
  (property "Reference" "R1"
    (at 100 45 0)
    (effects (font (size 1.27 1.27)))
  )
  (property "Value" "10k"
    (at 100 55 0)
    (effects (font (size 1.27 1.27)))
  )
  (property "Footprint" "Resistor_SMD:R_0402_1005Metric"
    (at 100 50 0)
    (effects (font (size 1.27 1.27)) hide)
  )
  (property "LCSC" "C25744"
    (at 100 50 0)
    (effects (font (size 1.27 1.27)) hide)
  )
  (pin "1" (uuid "pin1-uuid"))
  (pin "2" (uuid "pin2-uuid"))
  (instances
    (project "project_name"
      (path "/root-uuid" (reference "R1") (unit 1))
    )
  )
)

lisp

(symbol
  (lib_id "Device:R")
  (at 100 50 0)              ; x、y坐标，旋转角度（0、90、180、270）
  (unit 1)                   ; 多单元符号
  (exclude_from_sim no)
  (in_bom yes)
  (on_board yes)
  (dnp no)                   ; 不贴装（Do Not Populate）
  (uuid "symbol-uuid")
  (property "Reference" "R1"
    (at 100 45 0)
    (effects (font (size 1.27 1.27)))
  )
  (property "Value" "10k"
    (at 100 55 0)
    (effects (font (size 1.27 1.27)))
  )
  (property "Footprint" "Resistor_SMD:R_0402_1005Metric"
    (at 100 50 0)
    (effects (font (size 1.27 1.27)) hide)
  )
  (property "LCSC" "C25744"
    (at 100 50 0)
    (effects (font (size 1.27 1.27)) hide)
  )
  (pin "1" (uuid "pin1-uuid"))
  (pin "2" (uuid "pin2-uuid"))
  (instances
    (project "project_name"
      (path "/root-uuid" (reference "R1") (unit 1))
    )
  )
)

Wire

导线

lisp

(wire
  (pts
    (xy 100 50)
    (xy 120 50)
  )
  (stroke (width 0) (type default))
  (uuid "wire-uuid")
)

lisp

(wire
  (pts
    (xy 100 50)
    (xy 120 50)
  )
  (stroke (width 0) (type default))
  (uuid "wire-uuid")
)

Label (Local Net Name)

标签（本地网络名称）

lisp

(label "VCC"
  (at 100 50 0)
  (effects (font (size 1.27 1.27)))
  (uuid "label-uuid")
)

lisp

(label "VCC"
  (at 100 50 0)
  (effects (font (size 1.27 1.27)))
  (uuid "label-uuid")
)

Global Label (Cross-Sheet Net)

全局标签（跨页网络）

lisp

(global_label "USB_D+"
  (shape input)              ; input, output, bidirectional, tri_state, passive
  (at 150 60 0)
  (effects (font (size 1.27 1.27)))
  (uuid "global-uuid")
  (property "Intersheetrefs" "${INTERSHEET_REFS}"
    (at 150 60 0)
    (effects (font (size 1.27 1.27)) hide)
  )
)

lisp

(global_label "USB_D+"
  (shape input)              ; input、output、bidirectional、tri_state、passive
  (at 150 60 0)
  (effects (font (size 1.27 1.27)))
  (uuid "global-uuid")
  (property "Intersheetrefs" "${INTERSHEET_REFS}"
    (at 150 60 0)
    (effects (font (size 1.27 1.27)) hide)
  )
)

Power Symbol

电源符号

lisp

(symbol
  (lib_id "power:GND")
  (at 100 80 0)
  (unit 1)
  (exclude_from_sim yes)
  (in_bom no)
  (on_board yes)
  (uuid "power-uuid")
  (property "Reference" "#PWR01" ...)
  (property "Value" "GND" ...)
  (pin "1" (uuid "..."))
)

lisp

(symbol
  (lib_id "power:GND")
  (at 100 80 0)
  (unit 1)
  (exclude_from_sim yes)
  (in_bom no)
  (on_board yes)
  (uuid "power-uuid")
  (property "Reference" "#PWR01" ...)
  (property "Value" "GND" ...)
  (pin "1" (uuid "..."))
)

Hierarchical Sheet

层次化原理图页

lisp

(sheet
  (at 50 50)
  (size 30 20)
  (fields_autoplaced yes)
  (stroke (width 0.1524) (type solid))
  (fill (color 255 255 255 0))
  (uuid "sheet-uuid")
  (property "Sheetname" "Power Supply"
    (at 50 49 0)
    (effects (font (size 1.27 1.27)))
  )
  (property "Sheetfile" "power_supply.kicad_sch"
    (at 50 72 0)
    (effects (font (size 1.27 1.27)) hide)
  )
  (pin "VIN" input
    (at 50 55 180)
    (effects (font (size 1.27 1.27)))
    (uuid "sheet-pin-uuid")
  )
)

lisp

(sheet
  (at 50 50)
  (size 30 20)
  (fields_autoplaced yes)
  (stroke (width 0.1524) (type solid))
  (fill (color 255 255 255 0))
  (uuid "sheet-uuid")
  (property "Sheetname" "Power Supply"
    (at 50 49 0)
    (effects (font (size 1.27 1.27)))
  )
  (property "Sheetfile" "power_supply.kicad_sch"
    (at 50 72 0)
    (effects (font (size 1.27 1.27)) hide)
  )
  (pin "VIN" input
    (at 50 55 180)
    (effects (font (size 1.27 1.27)))
    (uuid "sheet-pin-uuid")
  )
)

3. PCB Format (.kicad_pcb)

3. PCB格式（.kicad_pcb）

File Structure

文件结构

lisp

(kicad_pcb
  (version 20231014)
  (generator "pcbnew")
  (generator_version "8.0")
  (general
    (thickness 1.6)
    (legacy_teardrops no)
  )
  
  ; Page settings
  (paper "A4")
  (title_block ...)
  
  ; Layer definitions
  (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)
    (46 "B.CrtYd" user "B.Courtyard")
    (47 "F.CrtYd" user "F.Courtyard")
    (48 "B.Fab" user)
    (49 "F.Fab" user)
  )
  
  ; Design rules setup
  (setup ...)
  
  ; Net definitions
  (net 0 "")
  (net 1 "GND")
  (net 2 "VCC")
  
  ; Footprints (component instances)
  (footprint ...)
  
  ; Traces
  (segment ...)
  
  ; Vias
  (via ...)
  
  ; Zones (copper pours)
  (zone ...)
  
  ; Graphics
  (gr_line ...)
  (gr_rect ...)
  (gr_circle ...)
  (gr_text ...)
)

lisp

(kicad_pcb
  (version 20231014)
  (generator "pcbnew")
  (generator_version "8.0")
  (general
    (thickness 1.6)
    (legacy_teardrops no)
  )
  
  ; 页面设置
  (paper "A4")
  (title_block ...)
  
  ; 层定义
  (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)
    (46 "B.CrtYd" user "B.Courtyard")
    (47 "F.CrtYd" user "F.Courtyard")
    (48 "B.Fab" user)
    (49 "F.Fab" user)
  )
  
  ; 设计规则设置
  (setup ...)
  
  ; 网络定义
  (net 0 "")
  (net 1 "GND")
  (net 2 "VCC")
  
  ; 封装（元件实例）
  (footprint ...)
  
  ; 走线
  (segment ...)
  
  ; 过孔
  (via ...)
  
  ; 敷铜区域
  (zone ...)
  
  ; 图形
  (gr_line ...)
  (gr_rect ...)
  (gr_circle ...)
  (gr_text ...)
)

Footprint

封装

lisp

(footprint "Package_SO:SOIC-8_3.9x4.9mm_P1.27mm"
  (layer "F.Cu")
  (uuid "footprint-uuid")
  (at 100 50 0)              ; x, y, rotation
  (descr "SOIC-8 package")
  (property "Reference" "U1"
    (at 0 -3.5 0)
    (layer "F.SilkS")
    (uuid "ref-uuid")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (property "Value" "ESP32-S3"
    (at 0 3.5 0)
    (layer "F.Fab")
    (uuid "val-uuid")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (property "Footprint" "Package_SO:SOIC-8..."
    (at 0 0 0)
    (layer "F.Fab")
    (hide yes)
    (uuid "fp-uuid")
  )
  
  ; Pads
  (pad "1" smd rect
    (at -1.905 -2.475)
    (size 0.6 1.5)
    (layers "F.Cu" "F.Paste" "F.Mask")
    (net 1 "GND")
    (uuid "pad-uuid")
  )
  (pad "2" thru_hole circle
    (at 0 0)
    (size 1.7 1.7)
    (drill 1.0)
    (layers "*.Cu" "*.Mask")
    (net 2 "VCC")
    (uuid "pad-uuid")
  )
  
  ; Silkscreen graphics
  (fp_line
    (start -2.5 -2.5)
    (end 2.5 -2.5)
    (stroke (width 0.12) (type solid))
    (layer "F.SilkS")
    (uuid "line-uuid")
  )
)

lisp

(footprint "Package_SO:SOIC-8_3.9x4.9mm_P1.27mm"
  (layer "F.Cu")
  (uuid "footprint-uuid")
  (at 100 50 0)              ; x、y坐标，旋转角度
  (descr "SOIC-8 package")
  (property "Reference" "U1"
    (at 0 -3.5 0)
    (layer "F.SilkS")
    (uuid "ref-uuid")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (property "Value" "ESP32-S3"
    (at 0 3.5 0)
    (layer "F.Fab")
    (uuid "val-uuid")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (property "Footprint" "Package_SO:SOIC-8..."
    (at 0 0 0)
    (layer "F.Fab")
    (hide yes)
    (uuid "fp-uuid")
  )
  
  ; 焊盘
  (pad "1" smd rect
    (at -1.905 -2.475)
    (size 0.6 1.5)
    (layers "F.Cu" "F.Paste" "F.Mask")
    (net 1 "GND")
    (uuid "pad-uuid")
  )
  (pad "2" thru_hole circle
    (at 0 0)
    (size 1.7 1.7)
    (drill 1.0)
    (layers "*.Cu" "*.Mask")
    (net 2 "VCC")
    (uuid "pad-uuid")
  )
  
  ; 丝印图形
  (fp_line
    (start -2.5 -2.5)
    (end 2.5 -2.5)
    (stroke (width 0.12) (type solid))
    (layer "F.SilkS")
    (uuid "line-uuid")
  )
)

Trace (Segment)

走线（线段）

lisp

(segment
  (start 100 50)
  (end 120 50)
  (width 0.25)
  (layer "F.Cu")
  (net 1)
  (uuid "segment-uuid")
)

lisp

(segment
  (start 100 50)
  (end 120 50)
  (width 0.25)
  (layer "F.Cu")
  (net 1)
  (uuid "segment-uuid")
)

Arc Trace

弧形走线

lisp

(arc
  (start 100 50)
  (mid 105 45)
  (end 110 50)
  (width 0.25)
  (layer "F.Cu")
  (net 1)
  (uuid "arc-uuid")
)

lisp

(arc
  (start 100 50)
  (mid 105 45)
  (end 110 50)
  (width 0.25)
  (layer "F.Cu")
  (net 1)
  (uuid "arc-uuid")
)

Via

过孔

lisp

(via
  (at 110 60)
  (size 0.8)
  (drill 0.4)
  (layers "F.Cu" "B.Cu")
  (net 1)
  (uuid "via-uuid")
)

lisp

(via
  (at 110 60)
  (size 0.8)
  (drill 0.4)
  (layers "F.Cu" "B.Cu")
  (net 1)
  (uuid "via-uuid")
)

Zone (Copper Pour)

敷铜区域

lisp

(zone
  (net 1)
  (net_name "GND")
  (layer "F.Cu")
  (uuid "zone-uuid")
  (hatch edge 0.5)
  (connect_pads
    (clearance 0.25)
  )
  (min_thickness 0.25)
  (filled_areas_thickness no)
  (fill yes
    (thermal_gap 0.5)
    (thermal_bridge_width 0.5)
  )
  (polygon
    (pts
      (xy 0 0)
      (xy 100 0)
      (xy 100 100)
      (xy 0 100)
    )
  )
  (filled_polygon
    (layer "F.Cu")
    (pts ...)
  )
)

lisp

(zone
  (net 1)
  (net_name "GND")
  (layer "F.Cu")
  (uuid "zone-uuid")
  (hatch edge 0.5)
  (connect_pads
    (clearance 0.25)
  )
  (min_thickness 0.25)
  (filled_areas_thickness no)
  (fill yes
    (thermal_gap 0.5)
    (thermal_bridge_width 0.5)
  )
  (polygon
    (pts
      (xy 0 0)
      (xy 100 0)
      (xy 100 100)
      (xy 0 100)
    )
  )
  (filled_polygon
    (layer "F.Cu")
    (pts ...)
  )
)

Board Outline

板框

lisp

(gr_rect
  (start 0 0)
  (end 100 100)
  (stroke (width 0.1) (type default))
  (fill none)
  (layer "Edge.Cuts")
  (uuid "outline-uuid")
)

lisp

(gr_rect
  (start 0 0)
  (end 100 100)
  (stroke (width 0.1) (type default))
  (fill none)
  (layer "Edge.Cuts")
  (uuid "outline-uuid")
)

4. Common Operations

4. 常见操作

Adding a Component to Schematic

向原理图添加元件

Add symbol to
```
(lib_symbols ...)
```
if not already present
Add
```
(symbol ...)
```
block with:
- Unique UUID
- Position
```
(at x y rotation)
```
- Reference property
- Value property
- Footprint property
- Pin mappings

若符号未在
```
(lib_symbols ...)
```
中，先添加该符号
添加
```
(symbol ...)
```
块，包含：
- 唯一UUID
- 位置
```
(at x y rotation)
```
- 参考编号属性
- 参数值属性
- 封装属性
- 引脚映射

Adding a Trace to PCB

向PCB添加走线

Find the net number for the connection
Add
```
(segment ...)
```
block with:
- Start and end coordinates
- Width
- Layer
- Net number
- Unique UUID

找到连接对应的网络编号
添加
```
(segment ...)
```
块，包含：
- 起点和终点坐标
- 线宽
- 所在层
- 网络编号
- 唯一UUID

Creating a Net

创建网络

In PCB file, add:
```
(net N "NetName")
```
Reference the net number in pads and segments

在PCB文件中添加：
```
(net N "NetName")
```
在焊盘和走线中引用该网络编号

5. Units and Coordinates

5. 单位与坐标

Context	Unit
Schematic	mils (1/1000 inch), stored as mm in file
PCB	millimeters
Angles	degrees (0, 90, 180, 270 typical)

Coordinates are absolute from origin (0,0).

场景	单位
原理图	mils（千分之一英寸），文件中以毫米存储
PCB	毫米
角度	度（常用0、90、180、270）

坐标以原点(0,0)为基准的绝对坐标。

6. UUID Generation

6. UUID生成

All elements require unique UUIDs. Format:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Generate with:

uuidgen

command or programming language UUID library.

所有元素都需要唯一的UUID。格式：

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

可通过

uuidgen

命令或编程语言的UUID库生成。

7. Parsing Tips

7. 解析技巧

Reading S-Expressions

读取S表达式

python

undefined

python

undefined

Simple recursive descent parser concept

简单递归下降解析器示例

def parse_sexpr(text): tokens = tokenize(text) return parse_list(tokens)

def parse_list(tokens): result = [] while tokens and tokens[0] != ')': if tokens[0] == '(': tokens.pop(0) result.append(parse_list(tokens)) else: result.append(tokens.pop(0)) if tokens: tokens.pop(0) # Remove closing ')' return result

undefined

def parse_sexpr(text): tokens = tokenize(text) return parse_list(tokens)

undefined

Writing S-Expressions

写入S表达式

Maintain consistent indentation (2 spaces)
Preserve existing UUIDs when editing
Keep order of elements as expected by KiCad
Use proper quoting for strings with spaces

保持一致的缩进（2个空格）
编辑时保留现有UUID
保持KiCad期望的元素顺序
对包含空格的字符串使用正确的引号

8. File Validation

8. 文件验证

After editing:

Open in KiCad to verify parsing
Run ERC/DRC via kicad-cli
Check for warnings about unknown tokens

Important: Always backup files before programmatic editing. KiCad may add/remove fields on save.

编辑后：

在KiCad中打开文件以验证解析是否正常
通过kicad-cli运行ERC（电气规则检查）/DRC（设计规则检查）
检查是否存在未知令牌的警告

重要提示： 在通过程序编辑文件前，请务必备份。KiCad在保存时可能会添加或删除字段。