Getting started using Python Scripts

Can someone point me to a step by step guide to using python scripts? That is, given that someone has a cool script that I want to use:

  1. where do I put that .py script?
  2. how do I invoke it?
  3. do I need to install Python separately or is it included in the KiCad install?
  4. do I need to set up a new path?
  5. what else?

I have tried copying the script into \KiCad\bin\scripting\plugins
And then (from within layout) Tools > Scripting Console, "import "
no dice.

Seems like there should be a clear document explaining this but I can’t find it.



Basics are explained here.

As an example of existing relatively complex plugins you can look here and here and here

To answer some of your questions

  1. Where you put it should work Put it in KiCad/share/kicad/scripting/plugins, look at complete list of paths in the doc I linked above
  2. Also explained in the doc. If you did everything right it will appear in pcbnew under tools->external plugins. If it doesn’t you can find some debug info by entering this in scripting console:
import pcbnew
print pcbnew.GetWizardsBackTrace()

It will show any exceptions that happened when importing your plugin.
3. On linux KiCad uses system python, on other platforms KiCad is shipped with it’s own python.
4. You don’t have to, see first doc I linked.
5. Be prepared to have to read c++ source code, python API is not well documented. Look at other plugins for help, @mmccoo’s blog also has lots of info on kicad scripting. Some of it is already outdated because API is not that stable, so again you will have to read c++ source code.


How about install addition python package using pypi / pip into KiCad python environment, not the Global python that install separately?

And how the global python environment and be reference to KiCad special package like pcbnew if I use the global install python instead of once in KiCad?

KiCad ships pip as well, you can install packages using it and it will be added to KiCad python’s environment.

That is tricky but should be doable. You have to make sure that and _pcbnew.pyd are on PYTHONPATH and PATH respectively when you use system python. And I am not sure what other dependencies those pull in.

1 Like

Oh, how about configuring PyCharm to use KiCad environment. I try, but seem to not working (pcbnew still not been recognized).

I use Intellij IDEA, I imagine PyCharm is similar.
Trick is to configure project to use system python sdk (2.7) and configure module to use KiCad python as interpreter. You will have to add KiCad python to interpreters list first.

1 Like

I have - but still can not see pcbnew – I forget if there is a way to specify the package at difference local other than add then in to the project source tree.

I am not sure I understood you correctly but if you are trying to add to your project you are doing it wrong. You need to add KiCad’s python.exe as interpreter in your IDE, then configure the module of your plugin to use that interpreter. IDE will automatically detect site-packages from kicad and among them, also it will configure path to pick up necessary dynamic libraries.
If you still can’t set it up post screenshots of your project setup, module setup and interpreters list.

EDIT: Looks like I misremembered the setup, once I got home I took some screenshots.

As you can see I have 3 python interpreters setup: system, kicad 4 and kicad 5. Note the path to python.exe and classpath. IDE picks those up automatically, you just need to point it to python.exe.

Project still uses system sdk but kicad5 python interpreter library that contains pcbnew and everything else that kicad python has in classpath (this library is generated automatically for each interpreter you add) is in dependency list.

That’s it. Oh and if you want to run your script from IDE, in your run configuration point it to kicad 5 python


I appreciate everyone’s comments. I am a circuit designer, I draw the schematic, generate the BOM, do the layout, build and test, and I write the code for the micro. But I don’t know what any of this stuff means. Do I need to get a computer science degree to use somebody’s Python script? This is waaaaaay too convoluted.

Oh, I thought you were looking to get started developing scripts. Now that I reread your first message I have no idea why :smiley:

If you just want to use someones script a good bet is to drop it into KiCad/share/kicad/scripting/plugins, unless it comes with instructions that say otherwise. Plugin will appear in pcbnew tools->external plugins menu after a restart.

1 Like

Thanks Qu1ck
I have checked that my script is in a folder with a valid path. In fact, there are a lot of scripts already in there. But when I click on Tools > External Plugins, there is nothing listed. Just the “Refresh Plugins” icon.
It seems that PCBNew is not reading those scripts. Any ideas on that?

There are different kind of scripts. Action plugins, footprint wizards. Which one are you trying to use?
You mentioned in first message that you put the script in KiCad\bin\scripting\plugins. That is not a valid path for pcbnew action plugin script. Use path I mentioned above.
Footprint wizards work differently.

1 Like

The script that I just put in there is called
It is in the folder C:\program files \kicad\share\kicad\scripting\plugins.
Also there are about 15 other .py files in there.
The first link you gave me explained how to show the paths that are searched, and this is one of them.
Some of the other file names in that directory are wizards, but not all (at least some of them don’t have the word “wizard” in their name).

Your path is correct, that means something is wrong with the script, maybe it’s not an action plugin at all. If you share it (on pastebin) I’ll be able to tell more.

  • Normal python script you can run from command line:

C:\Program Files\KiCad\bin\python.exe argument1 argument2…

  • BOM Generator script and be run from eeschema->Tools->Generate Bill Of Material. You can add more script by “+” buttons.
  • Footprint editor: Files->Create Footprint…, Then you see a list of footprint wizard scripts and/or you can add more on your own, and run from there.
  • PCBNEW: Two type of script
    • Action plugin: found from Tools->External Plugins… . These script load automatically if they are on the right location, and design as action plugin.
    • Console python script: Tools -> Scripting Console. From there, you can load and run many scripts that you can find or download for KiCad…

I don’t see “pastebin”… but here is a path to the file on github:

Look like you can run this script under pcbnew -> tool -> Console Scripting. Then type:

cd C:\ZYZYZ\ASFA\kicad_picknplace_assistant

I tried import kicad_picknplace_assistant, got an error “No Module named numpy”
that’s a reference to the third line in the file. I found numpy and (I think) installed it.
Do you know numpy? should I have to install it? If so, I must have done it wrong.

Yeah, I’m familiar with that script. It’s not easy to get to work on windows because of some dependencies.
Unless you need pdf output I recommend much more robust InteractiveHtmlBom plugin.

If you do need pdf output you have to run the script from command line, it’s not an action plugin.

So something like kicad/bin/python.exe path/to/pcb.kicad_pcb.
But I guarantee it won’t work at first and will print error about not being able to import matplotlib and numpy packages. Matplotlib is easy enough to install with pip but numpy is tricky.
If you need to go this route I will have to google to remember whats what.
Oh and this script will likely not work with kicad 5.

1 Like

Try to install the numpy module by pip: Under cmd console:
C:\Program…\KiCad\bin\python.exe -m pip install numpy
Then try run the script on the “normal” way under cmd console:
C:…\python.exe …

1 Like