Tutorials on python scripting in pcbnew

Hey all,

In an effort to help make kicad even better, I’ve put together some tutorials on using the python interface built into pcbnew. This first post serves as a table of contents for this thread.

The orlginal text of this first post:
In an effort to help make kicad even better, I’ve put together some tutorials on using the python interface built into pcbnew.

While many will be intimidated by the prospect of digging through C++ code, simple scripting can my more accessible.

I haven’t found any documentation on the python APIs that are available, so here I am.


So far, I’ve covered topics ranging from the basics of rathering netlist data, where are your wires, how to modify layout, zones. Most recently, I added a post on creating simple GUI forms for gathering information needed to do whatever you want your script to do.

I hope you find it helpful. Let me know if there’s something you’d like covered.


This is a test edit by Miles


There is a auto generated API documentation here. It’s not pretty but its easier to search and find something.

By the way I’ve seen your GUI tutorial. I myself experimented with adding new menu items to pcbnew. I succeeded but I couldn’t find a method to do it at startup.

Bookmarked! Thanks for sharing :slight_smile:

Read through everything last night. This is gold! :clap:
Very well written, I suspect you also did in-house education? :slight_smile:

I think community driven extensions to KiCad is the best idea ever, then you can please everybody.
The core devs can only do so much and the more people can learn to add functionality the better. I hope you enjoy writing these tutorials and continue updating with more posts. I will definitely follow.

Could you please do a for dummies post on how to actually use the scripts inside pcbnew? With pretty pictures of the console when you invoke the scripts and such. There are folks out there that are terrified of python too… like me.


Looks good, I’ve had a search through the python API, trying to find any reference to adding footprints from the librarys, for example adding mounting holes, which you can do manually.

Have you come across this? and if so, what functions are required to achieve it?

Thank you for taking the time and expending the effort to write these.

That’s helpful thank you. I’d seen doxygen stuff in the makefile but nothing showed up in my build area.

How did you add your menu item? I’ve tried to walk the wx tree for the top control bar, but it returns a wx control instead of the auitoolbar that it should.

on invoking the scripts, there’s not much too it, but the menu item can be easy to miss.

Go to the Tool menu in pcbnew. The last item should be scripting console. That will give you a popup with a python interpreter window.

There you can type python statements. One of those statements can be


where filepath is a path to a file.

It may be trickier in windows. I’m a linux guy.


Adding mounting holes. Funny you should mention it. I had the need to do that this week. I haven’t tried to script it yet, but some scripting is needed. Trying to position them in the corners of my boundary is tedious and I probably still didn’t get it right.

I’d be interested to see what you come up with. I’m not familiar with either python or the kicad API (just C++ for AVR - similar but different) and have so far been unable to identify the mechanism to place/import a footprint from a library into pcbnew.

The “basics” script crashes pcbnew with a segfault on latest nightly, linux version. Anyone else have the same issue?

Two possibilities come to mind, both of them have to do with the assumption of certain circuit elements.

First, the script assumes you have a net called clk. In the code, I do a find(’/clk’) without checking if anything is found. The subsequent call to .value()[0] then causes a seg fault for me if clk isn’t there.

Second, the script assume you have a module called U1. In this case, pcbnew doesn’t seg fault, but rather gives a cryptic message.

I’ve added a check for both in the code. Hopefully, that will fix your crash.

To get the full benefit of the demo, you’ll want to change clk and U1 to items you do have.

Sorry about that.

Here is my experiment. It has been sometime since I worked on this. I don’t know if it will work with latest build of pcbnew.

" the script assumes you have a net called clk."

Yes, that was it. Thanks

You did a great job. Explaning all that stuff.

I started scripting in KiCad 2 weeks ago and had to figure this stuff out all by myself. I also didn’t find the auto-generated API, until I stumbled across it in the manual.

Just one Question:
Did your pcbnew crash when you played around with Vias?
I’ve described that problem in this Post.

Edit: SOLVED it:
I forgot to set the Net.
Made some Quick Tests with Tracks and Vias:
-if Vias got the default NetCode 0, pcbnew crashes when zooming in
-tracks can have the default NetCode 0, without any problems
-if Vias got the default NetCode 0 and you move a component or change Canvas, a function is called, that sets the net to the net of the “connected” track

@dbrown2k I’ve posted a new entry on my blog on how to add additional modules to your design from pcbnew.

The short answer is this:

  • Find the directory that contains your kicad_mod files or clone it from the kicad github. Let’s say a variable footprint_lib points there
  • create an instance of the PCB_IO plugin:
    io = pcbnew.PCB_IO()
  • ask it for a new module instance
    mod = io.FootprintLoad(footprint_lib, "1pin")

Also note, that I’ve created a table of contents page for the blog:

@hyOzd thank you for the tip. I haven’t had a chance to play it, but it’s high on my list.

DougE The 0 netcode via crash seems like a bug. Where in the manual did you find the documentation link? Perhaps its a portion of the manual I haven’t seen yet.

dBman Glad it’s working for you and thank you for the bug report. :wink:


Hi all,

Is there a way to manipulate kicad’s view with python scripts?
What I want to achieve is:

  • find component by reference - easy one
  • ensure it is visible so that I can actually see it in the window
  • change zoom to such level that I can locate the component on the board (among other component)
    I did some search in the internet and read the python API but unfortunately couldn’t find anything appropriate.
    Maybe I am to stupid to find it or maybe it doesn’t exist.
    I need it to improve kicad assistance in manual pick & place work.
    Now the only way is to:
  • hit Ctrl+F
  • enter components reference and hit enter
  • hit escape
  • and finally zoom out using Alt + F2 as the default zoom after search is way to big ant therefore I can’t locate the component on the board - need to see some other component for sense of direction.
    And the whole process must be repeated for each component :frowning:
    Help please :slight_smile:

First of all, your tutorial blog is awesome!

I would like to second the question of how to modify the pcbnew editors state.

Is there way to select a group of objects using python scripting so they can be moved/rotated together? As if I clicked or lasso’ed hundrets of them manually?

The theory its easy, find a common Property of the items you wont to manipulate and search for them. The difficult thing is to find that property. You could use a filter to get your wanted Items out of the modules list. (My first though, the pcbnew.EDA_ITEM.IsSelected Property wont work, as you can’t select multiple items. Maybe another property will work.)

The easiest way, is to pass a list of References of the components you want to modify. Not very smart, but functional.

Another idea (I couldn’t test and look up yet) is, to use the Block Operations and get its Item list.

@DougE Getting the module objects I’d like to group/modify is the part I already know how to do. I got a list of module objects but I cant find any documentation on how to interact with the pcbnew UI. I’d like my script to select a known group of modules, as if I selected those parts using the mouse for block moving/manipulation.

The “Selected” property you mentioned looks like the right approach, but again, nothing I do seems to have any effect on the UI. I tried the “SetSelected()” method which causes “IsSelected()” to return true on multiple objects, but nothing happens in the UI. I can’t move/rotate/manipulate the selected group :confused:.