Symbol Libraries

Symbol libraries store reusable schematic components that can be placed in your designs. KiCad provides a comprehensive library management system for organizing, creating, and sharing symbols.

Overview

Symbol library management in KiCad is handled by the SYMBOL_LIBRARY_MANAGER class (source/eeschema/symbol_library_manager.h:27), which maintains working copies of libraries and tracks modifications.

Library Structure

LIB_SYMBOL Class

The core symbol class represents a library component:

// Source: eeschema/lib_symbol.h:82
class LIB_SYMBOL : public SYMBOL, public LIB_TREE_ITEM, public EMBEDDED_FILES
{
    wxString m_name;           // Symbol name
    LIB_ID m_libId;           // Library identifier
    std::weak_ptr<LIB_SYMBOL> m_parent;  // Parent for derived symbols
    LIB_ITEMS_CONTAINER m_drawings;      // Graphical elements
};

Symbols can be derived from parent symbols, inheriting properties and graphics while allowing customization. This enables efficient library organization.

Symbol Types

Standard Symbols

Regular components like resistors, capacitors, ICs

Power Symbols

Special symbols for power and ground nets

Derived Symbols

Symbols that inherit from parent symbols

Working with Libraries

Symbol Buffer System

The library manager uses a buffer system to track changes:

// Source: eeschema/symbol_library_manager.h:56
class SYMBOL_BUFFER
{
    std::unique_ptr<LIB_SYMBOL> m_symbol;   // Working copy
    std::unique_ptr<LIB_SYMBOL> m_original; // Initial state
    std::unique_ptr<SCH_SCREEN> m_screen;   // Symbol editor canvas
    
    bool IsModified() const;  // Check if symbol has been edited
};

Library Buffer

Each library has a buffer that tracks all symbols:

// Source: eeschema/symbol_library_manager.h:80
class LIB_BUFFER
{
    wxString m_libName;
    std::deque<std::shared_ptr<SYMBOL_BUFFER>> m_symbols;
    std::set<wxString> m_deleted;  // Deleted symbol names
    
    bool IsModified() const;  // Check if any symbols changed
};

Creating Custom Symbols

Open Symbol Editor

Launch the Symbol Editor from the schematic editor or main project window.

Create New Symbol

Start with a blank symbol or derive from an existing one:

void SetParent( LIB_SYMBOL* aParent = nullptr );
std::shared_ptr<LIB_SYMBOL> GetRootSymbol() const;
unsigned GetInheritanceDepth() const;

Add Graphics

Draw the symbol body using:

Rectangles for IC packages
Circles for discrete components
Arcs and lines for custom shapes
Text for labels and values

Place Pins

Add electrical pins with proper types:

Input, Output, Bidirectional
Power input/output
Passive, Open collector/emitter
Not connected

Each pin requires:

Pin number (matches footprint pad)
Pin name (displayed on schematic)
Electrical type (for ERC)
Graphic style (line, clock, inverted, etc.)

Set Properties

Configure symbol metadata:

Reference prefix (R, C, U, etc.)
Default value
Footprint filter patterns
Datasheet URL
Keywords for searching

Define Units

For multi-unit symbols (e.g., quad op-amp), create separate units:

int GetSubUnitCount() const override { return GetUnitCount(); }

Symbol Variants

Symbols can have alternate body styles (De Morgan representation):

struct LIB_SYMBOL_UNIT
{
    int m_unit;                       // Unit number
    int m_bodyStyle;                  // Alternate body style
    std::vector<SCH_ITEM*> m_items;   // Items for this unit/style
};

Use alternate body styles for logic gates to show both standard and De Morgan representations.

Library File Formats

Modern Format (.kicad_sym)

KiCad 6+ uses S-expression format:

(kicad_symbol_lib (version 20231120) (generator kicad_symbol_editor)
  (symbol "R" (pin_names (offset 0)) (in_bom yes) (on_board yes)
    (property "Reference" "R" (at 2.032 0 0)
      (effects (font (size 1.27 1.27))))
    (property "Value" "R" (at 0 0 90)
      (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 "R_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))))))
  )
)

Library Management

Adding Libraries

Libraries are managed through symbol library tables:

# Located in: ~/.config/kicad/8.0/sym-lib-table
(sym_lib_table
  (lib (name Device)(type KiCad)(uri ${KICAD8_SYMBOL_DIR}/Device.kicad_sym))
  (lib (name Connector)(type KiCad)(uri ${KICAD8_SYMBOL_DIR}/Connector.kicad_sym))
)

Library Adapter

The symbol library adapter provides a tree view interface:

// Source: eeschema/libraries/symbol_library_adapter.h
class SYMBOL_LIBRARY_ADAPTER
{
    // Populates symbol chooser with library contents
    // Filters by keywords and categories
};

Symbol Properties

Required Properties

Reference

string

required

Reference designator prefix (R, C, U, etc.)

Value

string

required

Component value or part number

Footprint

string

Associated PCB footprint

Datasheet

string

URL or path to component datasheet

Custom Properties

Add custom fields for:

Manufacturer part number
Supplier and supplier part number
Tolerance, power rating, voltage rating
Cost and availability information

Symbol Inheritance

Derived symbols inherit from parent symbols:

void SetParent( LIB_SYMBOL* aParent = nullptr );
std::weak_ptr<LIB_SYMBOL>& GetParent();
std::shared_ptr<LIB_SYMBOL> GetRootSymbol() const;

Derived symbols can override specific properties while inheriting graphics and pins from the parent. This is useful for creating symbol families (e.g., resistors with different power ratings).

Embedded Files

Symbols can embed files like datasheets:

class LIB_SYMBOL : public EMBEDDED_FILES
{
    // Embed PDF datasheets or images directly in symbol
};

Best Practices

Pin Numbering

Match physical package pin numbers exactly
Use standard numbering schemes (DIP: 1-N, QFP: clockwise from pin 1)
For multi-unit symbols, maintain consistent numbering across units

Graphic Standards

Use IEEE/ANSI or IEC standards for symbol shapes
Keep symbols visually balanced and readable
Standard pin length: 100 mils (2.54mm)
Standard grid: 50 or 100 mils

Property Management

Set visibility appropriately (reference: visible, value: visible, others: hidden)
Use footprint filters to constrain compatible footprints
Add comprehensive keywords for searchability

Library Organization

Group related symbols in dedicated libraries
Use clear, descriptive library and symbol names
Maintain separate project-specific and shared libraries
Version control your custom libraries

Source Code References

// Core symbol definition
// Location: source/eeschema/lib_symbol.h:82
class LIB_SYMBOL : public SYMBOL, public LIB_TREE_ITEM

Getting Started

Core Applications

Design Workflow

Advanced Features

Symbol Libraries

Overview

Library Structure

LIB_SYMBOL Class

Symbol Types

Standard Symbols

Power Symbols

Derived Symbols

Working with Libraries

Symbol Buffer System

Library Buffer

Creating Custom Symbols

Symbol Variants

Library File Formats

Modern Format (.kicad_sym)

Library Management

Adding Libraries

Library Adapter

Symbol Properties

Required Properties

Custom Properties

Symbol Inheritance

Embedded Files

Best Practices

Source Code References

Next Steps

Schematic Design

Footprint Libraries

Build docs developers (and LLMs) love

Getting Started

Core Applications

Design Workflow

Advanced Features

​Overview

​Library Structure

​LIB_SYMBOL Class

​Symbol Types

Standard Symbols

Power Symbols

Derived Symbols

​Working with Libraries

​Symbol Buffer System

​Library Buffer

​Creating Custom Symbols

​Symbol Variants

​Library File Formats

​Modern Format (.kicad_sym)

​Library Management

​Adding Libraries

​Library Adapter

​Symbol Properties

​Required Properties

​Custom Properties

​Symbol Inheritance

​Embedded Files

​Best Practices

​Source Code References

​Next Steps

Schematic Design

Footprint Libraries

Build docs developers (and LLMs) love

Overview

Library Structure

LIB_SYMBOL Class

Symbol Types

Working with Libraries

Symbol Buffer System

Library Buffer

Creating Custom Symbols

Symbol Variants

Library File Formats

Modern Format (.kicad_sym)

Library Management

Adding Libraries

Library Adapter

Symbol Properties

Required Properties

Custom Properties

Symbol Inheritance

Embedded Files

Best Practices

Source Code References

Next Steps