Arranging components in a circle with Kicad

I’ve been using kicad for just about all of my designs for a little over 5 years now. It took a little bit of a learning curve, but I’ve really come to love it, especially with the improvements by CERN that came out in version 4. One of the greatest features, in my opinion, is the Python Scripting Console in the PCB editor (pcbnew). It gives (more or less) complete access to the design hierarchy so that things like footprints can be manipulated in a scripted fashion.

In my most recent design, the LED Watch, I used this to script myself a tool for arranging footprints in a circle. What I want to show today was how I did it and how to use it so that you can make your own scripting tools (or just arrange stuff in a circle).

The python console can be found in pcbnew under Tools->Scripting Console.

Step 1: Write the script

When writing a script for pcbnew, it is usually helpful to have some documentation. Some can be found here, though I mostly used “dir” a whole bunch and had it print me the structure of the various things once I found the points to hook in. The documentation is fairly spartan at this point, so that made things easier.

Here’s my script:

There are several arguments to this function: a list of reference designators ([“D1”, “D2”, “D3”] etc), the angle at which the first component should be placed, the position in mils for the center of the circle, and the radius of the circle in mils. Once the function is invoked, it will find all of the components indicated in the reference designator list and arrange them into the desired circle.

Step 2: Save the script

In order to make life easier, it is best if the script is saved somewhere that the pcbnew python interpreter knows where to look. I found a good location at “/usr/share/kicad/scripting/plugins”, but the list of all paths that will be searched can be easily found by opening the python console and executing “import sys” followed by “print(sys.path)”. Pick a path that makes sense and save your script there. I saved mine as “” since I intend to add more functions to it as situations require.

Step 3: Open your PCB and run the script

Before you can use the scripts on your footprints, they need to be imported. Make sure you execute the “Read Netlist” command before continuing.

The scripting console can be found under Tools->Scripting Console. Once it is opened you will see a standard python (2) command prompt. If you placed your script in a location where the Scripting Console will search, you should be able to do something like the following:

Now, pcbnew may not recognize that your PCB has changed and enable the save button. You should do something like lay a trace or some other board modification so that you can save any changes the script made. I’m sure there’s a way to trigger this in Python, but I haven’t got around to trying it yet.


Hopefully this brief tutorial will either help you to place components in circles in Kicad/pcbnew or will help you to write your own scripts for easing PCB layout. Kicad can be a very capable tool and with its new expanded scripting functionality, the sky seems to be the limit.

8 thoughts on “Arranging components in a circle with Kicad

  1. Danielle

    Thanks! I was looking for a way to do this and stumbled upon your site. I noticed a few issues though. The first and most important being that the deg_per_idx turns into an integer (if placing items evenly spaced around a circle this causes a massive loss in precision for larger quantities), the second being that it seems to ignore the coordinates im giving it for the center, and third the component offset was left out of the equation for the orientation. The first and the third I managed to fix, but I’m not sure whats going on with the coordinates yet.

    I was hoping you had this on github so i could submit a pull request (or even better see if you had an updated version of this), but I don’t see it on there

    1. Pierre Schippes

      I try to learn scripting in kicad but i am complete new
      How you start the script afther loading it in the python shell

  2. Pierre Baillargeon

    I was looking for a way to programmatically assign X/Y coordinates to hundreds of footprints in pcbnew and landed on this post which helped me figure it out. Luckily, the syntax for working in millimeters was easy to guess at, but I thought I’d share for anyone else who may land here in the future. My simplified code (for one footprint, but can be extended as needed) is:
    from pcbnew import *
    part = pcb.FindModuleByReference(“YourFootPrintNameGoesHere”)

  3. Pierre Schippers


    Thank you for this information, i search for a possibility to place components in kicad 5.1 via python on linuw Mint. I try your script with a drawing of 16 leds. afther follow your example, the code print a list of my components i give in the command, code print finisch but my pcb drawing change nothing.

    What im missing ? can you advice me
    Thank you in advance

  4. Pierre Schippers

    Your script give me a tremendous push in the good direction, thank you. I search and found a way to renew the display after the script has do his job.

    you can add pcbnew.refresh() as the last action.
    I give this and my display refresh like it must be.


  5. Boguslaw

    Could you test this script in Kicad 5.1 ? I’m python noob and stuck with error
    Traceback (most recent call last):
    File “/usr/lib/python3.6/”, line 91, in runcode
    exec(code, self.locals)
    File “”, line 1, in
    File “/usr/share/kicad/scripting/plugins/”, line 26
    print “{0}: {1}”.format(rd, angle)
    SyntaxError: invalid syntax

    1. admin Post author

      No need to test it, I can tell you what’s wrong: The script needs to be ported to python3. It’s not hard: Just fix the print statements to use the print function instead.

    2. Frank Buss

      I ported it to Python 3 and KiCad 5.x, and also simplified how to pass the refs list:
      If you have lots of LEDs, you can also created it by script, e.g. with a list comprehension:
      [f”D{x}” for x in range(1,20)]
      [‘D1’, ‘D2’, ‘D3’, ‘D4’, ‘D5’, ‘D6’, ‘D7’, ‘D8’, ‘D9’, ‘D10’, ‘D11’, ‘D12’, ‘D13’, ‘D14’, ‘D15’, ‘D16’, ‘D17’, ‘D18’, ‘D19’]
      You can also easily change the function, for example to arrange it as a spiral.

Comments are closed.