KiCad API Python Bindings

kicad-python is the official Python bindings for the KiCad IPC API. This library makes it possible to develop scripts and tools that interact with a running KiCad session.

The KiCad IPC API replaces the legacy SWIG-based Python bindings for KiCad's PCB editor. The SWIG bindings still exist in KiCad 9 and 10, but are removed in KiCad 11.

For more information about the IPC API, please see the KiCad developer documentation. Specific documentation for developing add-ons is also available.

Note: Version 0.0.2 and prior of this package are an obsolete earlier effort and are unrelated to this codebase.

Requirements

Using the IPC API requires a suitable version of KiCad (9.0 or higher) and requires that KiCad be running with the API server enabled in Preferences > Plugins. This package also depends on the protobuf and pynng packages for communication with KiCad.

Note: Unlike the SWIG-based Python bindings, the IPC API requires communication with a running instance of KiCad. It is not possible to use kicad-python to manipulate KiCad design files without KiCad running.

Contributing

We welcome contributions in the form of issue reports, feature requests, and merge requests.

All general policies from https://dev-docs.kicad.org/en/rules-guidelines/index.html apply to the kicad-python project. Please make sure you have read all policies, especially the code contribution and tool-generated content policies, before creating an issue or merge request.

Please try to open issues in the correct repository (here for Python binding issues; the main KiCad code repository for general API issues) if you're able to determine whether or not the issue is specific to the Python bindings. It's OK to make mistakes here; we'll just move the issue to the correct repository.

Building from Source

Most users should use kicad-python by installing the latest version from PyPI. You can also build and install the library from this repository, to test unreleased changes or contribute to the development. For instructions on how to do so, please see COMPILING.md.

Note that this library builds against the API definitions (.proto files) in the kicad submodule. Official releases of the library to PyPI should use a tagged release of KiCad, but the development branch of kicad-python may sometimes move the submodule pointer to non-tagged commits during the course of development. If you are using this library from source rather than from PyPI, remember to keep the submodule updated and to test against a suitable build of KiCad, which may need to be a nightly or testing build in some situations. You can use the method KiCad.check_version to make sure you are using a compatible version of kicad-python for your installed version of KiCad.

Getting Started

To check that everything is working, install kicad-python (either follow the directions in COMPILING.md or else install the latest version from PyPI using pip install kicad-python). Launch KiCad, make sure the API server is enabled in Preferences > Plugins, and then you should be able to run:

$ python3 ./examples/hello.py

This should print out the version of KiCad you have connected to.

Documentation

The documentation created from this repository (via the docs directory and the docstrings in the source code) is hosted at https://docs.kicad.org/kicad-python-main

Many things are still not documented or underdocumented -- contributions that expand the documentation or add docstrings are welcomed.

Examples

Check out the repository for some example scripts that may serve as a starting point. Some of the examples are snippets that can be run directly from a terminal or your Python development environment, and some are KiCad action plugins that can be loaded into the PCB editor. For the plugins, copy or symlink them into the appropriate plugins path in order for KiCad to find them.

Release History

0.8.0 (August 30, 2026)

• Add Item.clone method to simplify creation of new items based on existing ones
• Add parent property to board types that can have a parent (e.g. board or footprint)
• Make "solder_paste_margin" and "solder_paste_margin_ratio" properties optional (Mark Hämmerling, !42)
• Add Board.get_layer_by_name
• Add Board.flip_items and Board.flip_items_by_id
• Expand wrappers for board stackup data

0.7.1 (April 17, 2026)

• Fix KiCad.run_action (leommxj)

0.7.0 (April 17, 2026)

• Add Board.get_items_by_id and groups support via Board.get_groups (requires KiCad 10) (Anthonypark, !15)
• Add support for barcodes and Board.get_barcodes (requires KiCad 10.0.1)
• Add support for reference images and Board.get_reference_images (requires KiCad 10.0.1)
• Add Board.set_title_block_info (requires KiCad 10.0.1)
• Add Board.get_connected_items, Board.get_items_by_net, and Board.get_items_by_netclass (requires KiCad 10.0.1)
• Fix several bounding box calculation bugs
• Support building with older versions of protoc

0.6.0 (March 15, 2026)

• Fix missing conversion of rectangles into polygons when rotating by non-cardinal amounts (#86)
• Move to pynng 0.9.0 (John Hagen, !37)
• Add locked properties to Track and ArcTrack (Anton Lazarev, !34)
• Add Board.get_layer_name (KiCad 9.0.8) (#94)
• Ensure PolygonWithHoles outline and holes are closed shapes (#73)
• Fix Project taking over the document passed into it (#78)
• Fix missing setter on Field.name (#87)

0.5.0 (October 13, 2025)

• Add Pad.pad_to_die_length (KiCad 9.0.4)
• Add Board.get_enabled_layers, Board.set_enabled_layers, and Board.get_copper_layer_count (KiCad 9.0.5)
• Autodetect default Flatpak socket path (Johannes Maibaum, !32)
• Add support for BoardCircle.rotate (@modbw, !33)

0.4.0 (July 8, 2025)

• Fix ability to move and rotate footprints
• Fix ArcTrack length calculation (Quentin Freimanis, !13)
• Make it possible to add new BoardPolygons in a more ergonomic way
• Add FootprintInstance.sheet_path property (#37)
• Add board.check_padstack_presence_on_layers, replacing FlashLayer in SWIG
• Allow setting Net.name so that new nets can be created
• Deprecate Net.code (net codes are an internal KiCad detail and API clients should ignore them)
• Add py.typed type hinting indicator file (John Hagen, !16)
• Fix Vector2.from_xy_mm type annotations (John Hagen, !17)
• Add Arc.angle and ArcTrack.angle; some arc angle utilities (Quentin Freimanis, !14)
• Add remove_items_by_id (Anthonypark, !20)
• Allow assigning nets to Zone (#62)
• Allow changing Pad.pad_type (#63)
• Allow changing Field.layer (#64)

0.3.0 (March 29, 2025)

• Add support for footprint mounting style attribute (#19) (Thanh Duong, !10)
• Added visible property to Field and deprecate it from TextAttributes to match KiCad changes
• Improve version checking functions(Lucas Gerads, !11)
• Add missing board layers User.10 through User.45 (#23)
• Improve padstack-related APIs for creating new vias and pads (#21)
• Change arc angle methods to return normalized angles; add degrees versions (#22)
• Add board.get_origin and board.set_origin (#20)
• Add ArcTrack.length (Thanh Duong, !12)
• Add Footprint.models (#31)
• Fix ability to create new graphic shapes on boards
• Fix the return value of Board.update_items and document it (#35)

0.2.0 (February 19, 2025)

• Updates for KiCad 9.0.0 release
• Fix util.board_layer.canonical_name names for technical layers
• Add board item selection management APIs
• Fix requirements.txt files in sample plugins
• Fix RecursionError when calling BoardCircle.__repr__ (#13)
• Relicense as MIT

0.1.2 (January 17, 2025)

• Updates for KiCad 9.0.0-rc2 release
• Fixes to plugin examples
• Add support for various project settings, board stackup, board file management
• Add helpers for board layer name conversions
• Change thermal spoke settings to match updated KiCad API
• Documentation improvements

0.1.1 (December 24, 2024)

• Bump dependency versions to fix compilation with newer protoc

0.1.0 (December 21, 2024)

Corresponding KiCad version: 9.0.0-rc1

First formal release of the new IPC-API version of this package. Contains support for most of the KiCad API functionality that is currently exposed, which is focused around the PCB editor to enable a transition path from existing SWIG-based plugins.