PCB back annotation in KiCAD with Python

KiCAD already provides a tool to automatically annotate your schematics before moving on to PCB. But I prefer to to annotate my components according to their PCB position. That makes it easier to locate a certain component when you have PCB on your hand and schematic is open in the computer screen.

Some tools such as Altium, provides such function. It works like this;

  • First you annotate your components in schematic (presumably according to their position in schematic sheet)
  • You switch to PCB side, complete the placing of your components
  • Re-annotate the components on PCB
  • Back-annotate name changes to the schematic

KiCad doesn’t have this feature. So I decided to give it a try at implementing this feature with KiCad’s python scripting interface. And I’m successful (I think..).

I’ve created a script that when you run it; re-names all components on your PCB according to their PCB position. Then updates your schematic files with these changes. You don’t have to lift a finger.

First of all my script doesn’t use the KiCad’s python API directly. Instead it uses a wrapper written in python which provides a more pythonic API. It’s called kicad-python and it’s on github. Unfortunately original project had some problems, so I had to fork it and add some missing features. So you have to use my fork instead.

You can find the script in examples/ folder of my kicad-python repository. Before running it make sure you BACKUP YOUR FILES.

Note that you don’t have to install ‘kicad-python’ on your system. You can use it from the downloaded location. There is only 1 dependency at the moment (other than obvious kicad installation), which you can install via pip:

  • enum34

Update: now kicad-python comes with it’s copy of the ‘enum34’ module. I’ve added it because at the moment installing python modules on kicad’s windows version seems to be a pain.

To run the script, load your board with pcbnew. Start the python console from “Tools->Scripting Console”. Make sure ‘kicad-python’ is in your path (if you haven’t installed it):

import sys

Run the script with:


After you run a script, pcbnew doesn’t update the view immediately. You can force it to redraw by cycling canvases. For ex; switch to original canvas mode then switch to opengl canvas. Let me know if you know a better method for this.

Important notes:

  • Backup your files before running the script.
  • Make sure you have a recent version of KiCad (at least 4.0)
  • Script won’t rename components if their names doesn’t end with a number. For ex. something like ‘D12X’ won’t be renamed!
  • Schematics are updated with simple string replacement. So it may not work in some cases. Unfortunately at the moment KiCad has scripting only for PCB
  • After you run the script, update the netlist files. When you read netlist from pcbnew, it shouldn’t change any component footprints. Otherwise something went wrong! It may update some (automatically given) net names though. That’s expected.
  • You should really backup your files!

If you have any problems/questions with the script please let me know. I will try to help as much as I can.

23 responses to “PCB back annotation in KiCAD with Python”

  1. Hi, I found your post on Kicad Forum but are having problems getting the script to work. this is the error message I get.

    Traceback (most recent call last):
    File “”, line 1, in
    File “C:/Users/i7/OneDrive/Programmer/Kicad/kicad-python/examples/pcbannotate.py”, line 31, in
    from kicad.pcbnew.board import Board
    File “C:/Users/i7/OneDrive/Programmer/Kicad/kicad-python/kicad/pcbnew/board.py”, line 23, in
    from kicad.pcbnew import drawing
    File “C:/Users/i7/OneDrive/Programmer/Kicad/kicad-python/kicad/pcbnew/drawing.py”, line 26, in
    from kicad.pcbnew import layer as pcbnew_layer
    File “C:/Users/i7/OneDrive/Programmer/Kicad/kicad-python/kicad/pcbnew/layer.py”, line 22, in
    from enum import IntEnum
    ImportError: No module named enum

    • Hey Martin,

      Please install ‘enum34’ python module. You can use pip to install it:

      pip install enum34

  2. Hi, when I use cmd in windows and try this code it says I have enum34 installed.

    If I try “pip install enum34” in kicad python console i get the message under.

    pip install enum34
    File “”, line 1
    pip(install enum34)
    SyntaxError: invalid syntax

    • Oh, that wasn’t a python command. You should run it from command line. If you were on linux, it would be really easy. But under windows it’s a little trickier.

      There is a lot of information on the web, how to install python modules with pip. But I’m guessing kicad comes with it’s own python distribution. I will have to check it and get back to you.

    • Ok, i’ve looked into this a bit. Installing pip for kicad’s python seems to be harder then i thought. But good thing is you don’t have to install ‘enum34’ library. You can use it from the source similar to ‘kicad-python’.

      Download the enum34 from here: https://pypi.python.org/pypi/enum34#downloads

      Add its path to ‘sys.path’ as you do with kicad-python:


      I hope this works for you. I will try to remove this dependency from kicad-python, or maybe I will distribute it with the library itself.

      Let me know if you have any problems.

  3. One step closer,

    Traceback (most recent call last):
    File “”, line 1, in
    File “C:/Users/i7/OneDrive/Programmer/Kicad/kicad-python/examples/pcbannotate.py”, line 48, in
    m = re.match(‘^((?:[a-zA-Z_\d]+[a-zA-Z_])|(?:[a-zA-Z_]+))(\d+)$’, prev_ref).groups()
    AttributeError: ‘NoneType’ object has no attribute ‘groups’

    • Well, that was a bug ๐Ÿ™‚ I’ve just pushed a commit that should fix it. Can you please try the latest version from github.

    • Please note; there is a slight issue with the naming. Components are numbered from top-left to bottom-right. But when you switch to back side of the bottom layer (you flip the board), this ordering becomes top-left to bottom-right. Which is inconsistent with the top-layer. I will fix this in the coming days.

  4. Hi, I haven’t tried your nice scripting yet. Does one be able to read out all x, y positions of all modules and edit them separately and then back annotate the new positions to KiCad? This would be a great chance to write one’s own placement algorithm or just some simple scripts to place the modules in a way that helps to reduce time consuming manual positioning …

    • Aquila, yes you can change the positions of modules using scripting. For example -using my fork of kicad-python- you can do:

      b = Board.from_editor()
      b.modules['R1'].position = (100,150)

      By the way, did you know that kicad has builtin auto placement feature? I can’t comment on its quality though.

  5. (Moderator – please delete previous comment. This one supersedes it.)

    I’m not familiar with python or the python shell of kicad and this is my first kicad project. I’m a newbie and would have found this example handy. It’s all explained in this excellent blog, but the blog assumes a level of familiarity which I didn’t have with any of the tools.

    (1) Get to github using the ‘my fork’ link above.
    (2) Using the green ‘Clone or Download’ button, I chose ‘Download Zip’ at the bottom
    (3) I put the zip in ‘/home/yourUserID/Downloads’, unzipped to create the ‘/home/yourUserID/Downloads/kicad-python-master/’ directory. This is the home. Observe the ‘examples’ subdirectory and the ‘pcbannotate.py’ file within it.
    (4) As directed, I selected ‘Tools | Scripting Console’ to open the KiCAD:PCBNEW – Python Shell.
    (5) Within the shell enter lines:
    (5a)import sys

    You are done!

    • John, I’m sorry I missed your comment. I’m glad you could figure it out yourself. Thanks for adding detailed steps.

  6. I.m new in Kicad and phyton.
    I tried to use your script following the steps. I Get the following error message

    Traceback (most recent call last):
    File “”, line 1, in
    File “C:\Users\morgalo\Documents\KICAD\pcbackannotate.py”, line 32, in
    from kicad.pcbnew.layer import Layer
    ImportError: cannot import name Layer

    any suggestion?

  7. The program works well, but I have found a bug. I am using Kicad Version: 4.0.6-e0-6349-53-ubuntu 16.04, release build. When I open Kicad and load the modified schematic file, Kicad crashes with a segmentation fault.
    The problem is that with a hierarchical schematic, the format for fields in the schematic file is different for the top level. Most of the schematics have a space after the F, e.g. ‘F 0’. The top layer has no space, e.g. ‘F0’.
    The schematic I have has a fuse with refDes of F1. The result is the program changes the field F1 to F101 because the replace function modifies the field line as if it was a refDes.

    S 5900 3150 1400 3150
    U 58C05EDB
    F0 “DSP” 60
    F101 “maincpu.sch” 60
    F2 “Itot_MesA” I L 5900 5400 79
    F3 “Itot_MesB” I L 5900 5600 79″

    That causes a segmentation fault.

    It shows how difficult it is to verify code. In this case, it is sensitive to the schematic and to the version of KiCad. Perhaps KiCad will be changed so all the field designaters will will have the same format, with the space.

    Great program.

    • Hey Karsten, thanks for reporting this. Main reason is that, script does a very dummy regex replacement ๐Ÿ™‚ You know what they say about regex…

      I will look in to a fix. In the mean time, there have been other attempts at creating back annotation tools. You can find it on forum.kicad.info . Maybe they are better.

  8. I am new to Python and FreeCAD. “More pythonic” sounds cool, but how bad would this script be if it was written entirely in FreeCAD’s Python? Can it be done? If yes, would that not be a far better first step into this area?

  9. Hey, Thanks a lot for this script! It worked just perfectly. In my case it was needed to close Eeschema while executing the script! Maybe you could add this note to the list above!

    • FYI I heard there will be built in support for back annotation in Kicad 6. So there won’t be any need for this script ๐Ÿ™‚

Leave a Reply

Your email address will not be published.