HOWTO: Register a python plugin inside pcbnew Tools menu

Hi all,

A new feature is now available for testing in KiCad daily build (PPA Ubuntu).
This feature allow you to create a menuentry on pcbnew at this place:

This new menu entry will call a python action/plugin.

To use it:

Compilation option

Be sure to use KiCad with KICAD_SCRIPTING_ACTION_MENU option activated (this is the case for PPA Ubuntu since yesterday).

Install the plugin

The following script is an example:

import pcbnew
import re
import datetime

class text_by_date( pcbnew.ActionPlugin ):
    def defaults( self ): = "Add date on PCB"
        self.category = "Modify PCB"
        self.description = "Automaticaly add date on an existing PCB"

    def Run( self ):
        pcb = pcbnew.GetBoard()
        for draw in pcb.m_Drawings:
            if draw.GetClass() == 'PTEXT':
                txt = re.sub( "\$date\$ [0-9]{4}-[0-9]{2}-[0-9]{2}",
                                 "$date$", draw.GetText() )
                if txt == "$date$":
                    draw.SetText( "$date$ %s" )


This example script is took from sources:

If package kicad-demo is installed, a copy is present at

Copy (or create) this file at the right places to install it:

  • Single user installation (home directory based): ~/.kicad_plugins/
  • System wide: /usr/share/kicad/scripting/plugins/

After this, you can refresh plugin list (or restart kicad). A new menu entry is available:

Use the plugin

This (small) example plugin try to find any text field on the board file and if the text is “$date$”, it automaticaly change it by “$date$” + the current date.



Of course this example is really trivial. Anyway you can imaginate a large number of things with the python interface.

Keep in mind that python interface is not completly stable and your scripts needs to be written with care !

In KiCad demo there are 3 example provided:

  • The example above
  • An example to automaticaly add or update border/pcb edges
  • 4 examples to tests undo/redo features.

This is awesome! Thank you very much. :slight_smile:

Is this for python plugins only or can we add tools made with the tool framework aswell?

It’s only for python since it’s loading python scripts only.

Hi @jsreynaud
very nice, configurable and useful tool!
it was since my first release of kicad StepUp I was looking forward for a simple button to execute a script! :smiley:
Do you think it would be possible to also add an icon (svg or png) beside the name? = "Add date on PCB" self.icon ="my nice icon here.svg"

Hi @maui

Yes, this is a feature I want to add in the future…
For the moment this feature is there for testing. I’m expecting more feedback (bugs, errors…) before adding new features.

Ok then…
I’m adapting my script to check annular rings of the displayed pcb board as a plugin and it works, but because the result of checking is printed, all messages are missed… is there a way to print or see the messages when executing the action script?

Yes, If you open kicad from a shell, you should be able to see your message on this shell directly.

hummm …
I forgot to tell you I’m in windows … and there nothing can be seen when running pcbnew from console

Ok so you can for example use some wx message box:

import wx

wx.MessageDialog(None,“My message”)



I had to write:

wx.LogMessage(“My message”)

to see the window
but this is fine for me :wink:


Would it be possible to execute scripts on specific events? Like on import of netlist.
I would like to make the revision on the silkscreen update from the revision in the netlist/schematic

This feature is also planned. Not yet available.


Hi again,
I noticed that when a script is executed, the board get touched and Save button become enabled…
The same script if launched in python scripting console doesn’t do the same…
Is that something expected?
Here a simple example that triggers Save Button…

import wx
import pcbnew
from pcbnew import *

class minimal_test( pcbnew.ActionPlugin ):

def defaults( self ):
    Method defaults must be redefined should be the menu label to use
    self.category should be the category (not yet used)
    self.description should be a comprehensive description
      of the plugin
    """ = "minimal test"
    self.category = "Checking PCB"
    self.description = "minimal test"
def Run( self ):


Do you know why this nice tool is not available as default in nightly builds?
I use to build my own copy of kicad, but I discovered that in windows nightly it is not enabled …


here a first Action Plugin Script converted from python console to AP :slight_smile:



KiCad is unable to detect what your script is trying to do. So it assume that the script is modify the board.
An history in the undo/redo list is added and the board is marked as changed.
Event if you script doesn’t modify anything …

About nightly build I’ll ask to @nickoe.



yes, I noticed in the the cpp code

would be nice to have a return code from the python script (i.e. default = 1 #‘board modified’) that the script can assign to 0 (board unmodified) so the board can be marked as changed only if the script is doing something that really change it?

that will allow a large amount of users to have this useful option enabled and will give developers a useful feedback …
Very little amount of users are building kicad from source…
In fact this Action Plugin does not add any risk to those already present with the python console, but it is giving a more user friendly way to use python inside Kicad
Looking forward to see it in Nightly :wink:


I look forward too. I am on a mac :slight_smile:

1 Like

I had also ask to @adamwolf for that point.

1 Like

I think I can automatically detect if there are some modifications or not. I’ll try this autodetection on a future patch.

1 Like

it seems that now the Action Plugin is delivered with the Nigtlies :smiley:

Application: kicad
Version: (2017-04-13 revision c4ea54227)-makepkg, release build
Libraries: wxWidgets 3.0.2
libcurl/7.52.1 OpenSSL/1.0.2k zlib/1.2.11 libssh2/1.8.0 nghttp2/1.19.0 librtmp/2.3
Platform: Windows 8 (build 9200), 64-bit edition, 64 bit, Little endian, wxMSW

  • Build Info -
    wxWidgets: 3.0.2 (wchar_t,wx containers,compatible with 2.8)
    Boost: 1.60.0
    Curl: 7.52.1
    KiCad - Compiler: GCC 6.3.0 with C++ ABI 1010

From now on, having a larger testing audience is much easier :wink: