# KiCad API Python Bindings
`kicad-python` is the official Python bindings for the [KiCad](https://kicad.org) IPC API. This
library makes it possible to develop scripts and tools that interact with a running KiCad session.
The KiCad IPC API can be considered in "public beta" state with the release of KiCad 9 (currently
planned for on or around February 1, 2025). The existing SWIG-based Python bindings for KiCad's
PCB editor still exist in KiCad 9, but are in maintenance mode and will not be expanded.
For more information about the IPC API, please see the
[KiCad developer documentation](https://dev-docs.kicad.org/en/apis-and-binding/ipc-api/index.html).
Specific documentation for developing add-ons is
[also available](https://dev-docs.kicad.org/en/apis-and-binding/ipc-api/for-addon-developers/index.html).
> 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
Please file bug reports and feature requests in this Gitlab project. The team may move them to the
main KiCad repository depending on the nature of the request.
Merge requests are welcome for minor fixes and improvements. More significant changes should be
discussed with the development team (via email, or in an issue) first.
## 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:
```sh
$ 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.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 `BoardPolygon`s 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.
Raw data
{
"_id": null,
"home_page": "https://kicad.org/",
"name": "kicad-python",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "The KiCad Development Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9c/50/df6b360e5769acd8d773d03100174272c494e368464479dcb971847b2c4a/kicad_python-0.4.0.tar.gz",
"platform": null,
"description": "# KiCad API Python Bindings\n\n`kicad-python` is the official Python bindings for the [KiCad](https://kicad.org) IPC API. This\nlibrary makes it possible to develop scripts and tools that interact with a running KiCad session.\n\nThe KiCad IPC API can be considered in \"public beta\" state with the release of KiCad 9 (currently\nplanned for on or around February 1, 2025). The existing SWIG-based Python bindings for KiCad's\nPCB editor still exist in KiCad 9, but are in maintenance mode and will not be expanded.\n\nFor more information about the IPC API, please see the\n[KiCad developer documentation](https://dev-docs.kicad.org/en/apis-and-binding/ipc-api/index.html).\nSpecific documentation for developing add-ons is\n[also available](https://dev-docs.kicad.org/en/apis-and-binding/ipc-api/for-addon-developers/index.html).\n\n> Note: Version 0.0.2 and prior of this package are an obsolete earlier effort and are unrelated to\n> this codebase.\n\n## Requirements\n\nUsing the IPC API requires a suitable version of KiCad (9.0 or higher) and requires that KiCad be\nrunning with the API server enabled in Preferences > Plugins. This package also depends on the\n`protobuf` and `pynng` packages for communication with KiCad.\n\n> Note: Unlike the SWIG-based Python bindings, the IPC API requires communication with a running\n> instance of KiCad. It is not possible to use `kicad-python` to manipulate KiCad design files\n> without KiCad running.\n\n## Contributing\n\nPlease file bug reports and feature requests in this Gitlab project. The team may move them to the\nmain KiCad repository depending on the nature of the request.\n\nMerge requests are welcome for minor fixes and improvements. More significant changes should be\ndiscussed with the development team (via email, or in an issue) first.\n\n## Building from Source\n\nMost users should use `kicad-python` by installing the latest version from PyPI. You can also\nbuild and install the library from this repository, to test unreleased changes or contribute to\nthe development. For instructions on how to do so, please see `COMPILING.md`.\n\nNote that this library builds against the API definitions (`.proto` files) in the `kicad` submodule.\nOfficial releases of the library to PyPI should use a tagged release of KiCad, but the development\nbranch of `kicad-python` may sometimes move the submodule pointer to non-tagged commits during the\ncourse of development. If you are using this library from source rather than from PyPI, remember\nto keep the submodule updated and to test against a suitable build of KiCad, which may need to be\na nightly or testing build in some situations. You can use the method `KiCad.check_version` to\nmake sure you are using a compatible version of `kicad-python` for your installed version of KiCad.\n\n## Getting Started\n\nTo check that everything is working, install `kicad-python` (either follow the directions in\nCOMPILING.md or else install the latest version from PyPI using `pip install kicad-python`).\nLaunch KiCad, make sure the API server is enabled in Preferences > Plugins, and then you should be\nable to run:\n\n```sh\n$ python3 ./examples/hello.py\n```\n\nThis should print out the version of KiCad you have connected to.\n\n## Documentation\n\nThe documentation created from this repository (via the `docs` directory and the docstrings in the\nsource code) is hosted at https://docs.kicad.org/kicad-python-main\n\nMany things are still not documented or underdocumented -- contributions that expand the\ndocumentation or add docstrings are welcomed.\n\n## Examples\n\nCheck out the repository for some example scripts that may serve as a starting point. Some of the\nexamples are snippets that can be run directly from a terminal or your Python development\nenvironment, and some are KiCad action plugins that can be loaded into the PCB editor. For the\nplugins, copy or symlink them into the appropriate plugins path in order for KiCad to find them.\n\n## Release History\n\n### 0.4.0 (July 8, 2025)\n\n- Fix ability to move and rotate footprints\n- Fix ArcTrack length calculation (Quentin Freimanis, !13)\n- Make it possible to add new `BoardPolygon`s in a more ergonomic way\n- Add `FootprintInstance.sheet_path` property (#37)\n- Add `board.check_padstack_presence_on_layers`, replacing FlashLayer in SWIG\n- Allow setting `Net.name` so that new nets can be created\n- Deprecate `Net.code` (net codes are an internal KiCad detail and API clients should ignore them)\n- Add `py.typed` type hinting indicator file (John Hagen, !16)\n- Fix `Vector2.from_xy_mm` type annotations (John Hagen, !17)\n- Add `Arc.angle` and `ArcTrack.angle`; some arc angle utilities (Quentin Freimanis, !14)\n- Add `remove_items_by_id` (Anthonypark, !20)\n- Allow assigning nets to `Zone` (#62)\n- Allow changing `Pad.pad_type` (#63)\n- Allow changing `Field.layer` (#64)\n\n### 0.3.0 (March 29, 2025)\n\n- Add support for footprint mounting style attribute (#19) (Thanh Duong, !10)\n- Added `visible` property to `Field` and deprecate it from `TextAttributes` to match KiCad changes\n- Improve version checking functions(Lucas Gerads, !11)\n- Add missing board layers User.10 through User.45 (#23)\n- Improve padstack-related APIs for creating new vias and pads (#21)\n- Change arc angle methods to return normalized angles; add degrees versions (#22)\n- Add `board.get_origin` and `board.set_origin` (#20)\n- Add `ArcTrack.length` (Thanh Duong, !12)\n- Add `Footprint.models` (#31)\n- Fix ability to create new graphic shapes on boards\n- Fix the return value of `Board.update_items` and document it (#35)\n\n### 0.2.0 (February 19, 2025)\n\n- Updates for KiCad 9.0.0 release\n- Fix `util.board_layer.canonical_name` names for technical layers\n- Add board item selection management APIs\n- Fix `requirements.txt` files in sample plugins\n- Fix RecursionError when calling `BoardCircle.__repr__` (#13)\n- Relicense as MIT\n\n### 0.1.2 (January 17, 2025)\n\n- Updates for KiCad 9.0.0-rc2 release\n- Fixes to plugin examples\n- Add support for various project settings, board stackup, board file management\n- Add helpers for board layer name conversions\n- Change thermal spoke settings to match updated KiCad API\n- Documentation improvements\n\n### 0.1.1 (December 24, 2024)\n\n- Bump dependency versions to fix compilation with newer protoc\n\n### 0.1.0 (December 21, 2024)\n\n*Corresponding KiCad version: 9.0.0-rc1*\n\nFirst formal release of the new IPC-API version of this package. Contains support for most of the\nKiCad API functionality that is currently exposed, which is focused around the PCB editor to enable\na transition path from existing SWIG-based plugins.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "KiCad API Python Bindings",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://kicad.org/",
"Repository": "https://gitlab.com/kicad/code/kicad-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2402fba3f66ab24c8ec9bfe06a1aa20121d5147dfad3fa226d002c9c465d1ba0",
"md5": "d4f808586079d9105b745ab7835f3942",
"sha256": "ff7b38f919becd34da74dd061773a4dc813d0affc8f89cc65523e4d00e758936"
},
"downloads": -1,
"filename": "kicad_python-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4f808586079d9105b745ab7835f3942",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 128707,
"upload_time": "2025-07-08T21:33:04",
"upload_time_iso_8601": "2025-07-08T21:33:04.790348Z",
"url": "https://files.pythonhosted.org/packages/24/02/fba3f66ab24c8ec9bfe06a1aa20121d5147dfad3fa226d002c9c465d1ba0/kicad_python-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9c50df6b360e5769acd8d773d03100174272c494e368464479dcb971847b2c4a",
"md5": "614f6e14b8a82a8e9148386c14734b08",
"sha256": "c6313646740893af40b165dd66c58ff7d3268a1b475dd6183d933d21272b79d0"
},
"downloads": -1,
"filename": "kicad_python-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "614f6e14b8a82a8e9148386c14734b08",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 196180,
"upload_time": "2025-07-08T21:33:06",
"upload_time_iso_8601": "2025-07-08T21:33:06.048219Z",
"url": "https://files.pythonhosted.org/packages/9c/50/df6b360e5769acd8d773d03100174272c494e368464479dcb971847b2c4a/kicad_python-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 21:33:06",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "kicad",
"gitlab_project": "code",
"lcname": "kicad-python"
}
JSON