KiCad IPC API

The IPC API is an interface that can be used to remotely control a running instance of KiCad. This can be used to implement KiCad plug-ins as well as to interface KiCad with external software. The API is currently under development, with the plan of stabilizing the first version for KiCad 9.0.

During initial development of the API, documentation and stability are not as high priorities as they will be once the API has stabilized. We will document things on a best-effort basis, but please be aware that during the KiCad 9.0 development cycle (i.e. during the 8.99 nightly builds), information described here and in other API documentation is subject to change without notice.

Contributing to the API

During initial development, the API efforts are being coordinated between members of the KiCad core team and community contributors. While we welcome help, the work is expected to be less stable and more dynamic until the release of KiCad 9.0. If you are interested in contributing to the API in any way, please contact Jon Evans. Merge requests made without first contacting the API team may be rejected if they do not align with our plans; please get in touch first to make sure your efforts are not wasted.

Overall Design Principles

The KiCad API is implemented using Protocol Buffers to define the structure and contents of messages, and NNG to transport messages between processes using UNIX sockets. This implementation supports all supported KiCad platforms, including Windows, macOS, and many Linux/BSD variants. Each running KiCad instance acts as a server when the API is enabled, and plugins and other applications act as clients which open connections to KiCad.

KiCad is an event-driven GUI application, and like most other such applications, it operates a single thread that handles all events (background worker threads are used for certain computations to improve performance). While the API server itself is decoupled from the rest of KiCad, API events are handled like any other form of user input, and thus are synchronous. This is an important difference from other APIs that users may be used to (for example, APIs for web services) which are often asynchronous to some extent. In practice, this means a few things must be kept in mind:

The KiCad user may be doing something with the application that blocks the API, in order to prevent out-of-order event issues and to prevent third-party software from disrupting the user. This means that API clients need to anticipate that API messages may sometimes timeout or fail because KiCad is busy, and should have a facility to retry requests.
An application should not open multiple connections to KiCad at the same time. While the underlying transport layer supports this, KiCad itself will force an ordering of handling API requests and so there is no advantage to doing so.

The API surface described by Protocol Buffers messages ("protobufs") is stable following the best practices described by the Protocol Buffers team. In general, this means that new versions of KiCad may introduce new messages and fields, but will not modify the meaning of existing messages and fields. Items in the API may be deprecated over time; deprecated messages and fields will be supported for at least one major version of KiCad after the deprecation is announced.

Plugins developed for the IPC API are launched in standalone processes that then communicate with the KiCad process that launched them. Environment variables are used to inform the plugin about the IPC socket path and a unique identifier for the running KiCad instance. This allows multiple instances of KiCad to run side-by-side and launch plugins that can communicate with the correct instance. Third-party software that is not launched as a KiCad plugin can also communicate with any running KiCad instance, however it is up to the third-party software to decide how (and if) to handle the case of multiple running KiCad instances.

Detailed information

The For KiCad Developers section contains information on the technical implementation of the API on the C++ side, and guidelines for modifying and extending the API. Please read this section before working on contributions that touch the API.

The For Add-on Developers section contain information for users of the API. Please read this section if you are interested in developing KiCad plugins or interfaces with third-party software.