Reference manual

This document is Copyright © 2010-2020 by its contributors as listed below. You may distribute it and/or modify it under the terms of either the GNU General Public License (, version 3 or later, or the Creative Commons Attribution License (, version 3.0 or later.

All trademarks within this guide belong to their legitimate owners.


Jean-Pierre Charras, Fabrizio Tappero, Wayne Stambaugh, Jon Evans


Please direct any bug reports, suggestions or new versions to here:

Introduction to Pcbnew

Initial configuration

When Pcbnew is run for the first time, if the global footprint table file fp-lib-table is not found in the KiCad configuration folder, Pcbnew will ask how to create this file:

TODO: add screenshot
TODO: add instructions on what these options mean

The default footprint library table includes all of the standard footprint libraries that are installed as part of KiCad.

The Pcbnew user interface

pcbnew overview

The main Pcbnew user interface is shown above, with some key elements indicated:

  1. Top toolbars

  2. Left toolbar

  3. Message panel and status bar

  4. Right toolbar (drawing and design tools)

  5. Appearance panel

  6. Selection filter panel

The editing canvas is a view onto the board being designed. You can pan and zoom to different areas of the board, and also flip the view to show the board from the bottom.

By default, dragging with the middle or right mouse button will pan the canvas view, and scrolling the mouse wheel will zoom the view in or out. You can change this behavior in the Mouse and Touchpad section of the preferences (see Configuration and Customization for details).


TODO: Write this section

Display and selection controls

Board layers

Layers in Pcbnew represent physical copper layers on a board, as well as graphical layers used for defining things such as silkscreen, solder mask, and the board edge. There is always one layer that is active in the editor. The active layer is drawn on top of other layers, and will be the layer assigned to newly-created objects. The active layer is indicated in the layer selector drop-down box in the top toolbar, and is also highlighted in the appearance panel. To change the active layer, you can click a layer name in the appearance panel, use the drop-down layer selector in the top toolbar, or use a hotkey. Layers can be hidden to simplify the board view. You can hide a layer even if it is the active layer.

The appearance panel

The appearance panel provides controls to manage the visibility, color, and opacity of objects in the Pcbnew drawing canvas. It has three tabs: the Layers tab contains controls for the board layers, the Objects tab contains controls for different types of graphical objects, and the Nets tab contains controls for the appearance of the ratsnest and copper items.

Layer controls

In the Layers tab of the appearance panel, each board layer is shown with its color and visibility state. The active layer is shown highlighted with an arrow indicator to the left of the color swatch. Left-click on a layer to choose it as the active layer. Left-click on the corresponding visibility icon to toggle the layer between visible and hidden. Double-click or middle-click on the color swatch to change the layer’s color.

You must first create a custom color theme in Preferences before you can change layer colors in the appearance panel.

Below the list of layers is an expandable panel that contains layer display options. The first setting controls how non-active layers are displayed: normal, dimmed, or hidden. The layer display mode can be used to simplify the view and focus on a single layer. Items on inactive layers cannot be selected when the non-active layer display mode is "Dim" or "Hide". You can use the hotkey Ctrl+H to cycle through these display modes quickly.

Flip board view will show the board as if you are looking from the bottom (that is, mirrored around the Y-axis). This option is also available in the View menu.

Object controls

The Objects tab of the appearance panel is similar to the Layers tab. The main differences are that some objects have no color setting, and that four types of objects (tracks, vias, pads, and zones) have opacity control sliders. The opacity setting here will be multiplied with any opacity set in the layer colors. By default, all objects are fully opaque except for zones, which are set to translucent in order to make it easier to see objects through filled zone areas.

Layer presets

Layer presets store which layers and objects are visible and hidden for easy recall. There are several built-in layer presets, and you can save your own custom presets. Custom presets are stored in the project settings for a board, as presets may be specific to a certain board stackup.

To load a preset, choose it from the Presets drop-down menu at the bottom of the appearance panel, or use the quick switcher by holding down Ctrl and pressing Tab. Once the quick switcher window appears, you can press Tab and Shift+Tab to cycle through the available presets. When you let go of the Ctrl key, the highlighted preset will be loaded.

To save a custom preset, first use the visibility controls to choose which layers you want visible, then choose Save Preset…​ from the Presets drop-down menu. Give your preset a name, and it will now be available via the drop-down menu and the quick switcher. To modify a custom preset, follow the same process and save the modified version with the same name to overwrite the existing version. To delete a custom preset, choose the Delete Preset…​ option from the drop-down menu and select the preset to be deleted from the list.

Net and net class controls

The Nets tab of the appearance panel shows a list of all nets and net classes in the board. Each net has a visibility control that controls the visibility of that net in the ratsnest. Hiding nets in the ratsnest does not change the connectivity of the board and will not impact the design rule checker; it only is intended to make the ratsnest easier to understand.

Each net and net class can also have a color assigned. By default, this color applies to the ratsnest lines for the net (or for all the nets in the net class). Nets have no color by default; this is indicated by a checkerboard pattern in the color swatch. Double-click or right-click a net or net class color swatch to set the color.

The Default net class cannot have a color assigned, as nets in this class will just use the default ratsnest color defined by the color theme.

You can also select and highlight nets and net classes via the appearance panel: right-click on a net or net class to show these options in a menu.

Below the list of net classes is an expandable panel that contains net display options. The first option controls how net colors are applied. When "All" is selected, all copper items (pads, tracks, vias, and zones) belonging to a net or net class will take on the chosen color. When "Ratsnest" is selected (the default value), only the ratsnest is affected by net and net class colors. When "None" is selected, net and net class colors are ignored.

The second option controls how ratsnest lines are drawn. "All layers" means that ratsnest lines will be drawn between all unconnected items. "Visible layers" means that no ratsnest lines will be drawn to items that are on hidden layers, even when those items are unconnected.

Selection and the selection filter

Selecting items in the editing canvas is done with the left mouse button. Single-clicking on an object will select it, and dragging will perform a box selection. A box selection from left to right will only select items that are fully inside the box. A box selection from right to left will select any items that touch the box. A left-to-right selection box is drawn in yellow, and a right-to-left selection box is drawn in blue.

The selection action can be modified by holding modifier keys while clicking or dragging:

Modifier Keys (Windows/Linux) Modifier Keys (macOS) Selection Effect



Add item(s) to the existing selection.

Alt + Shift

Cmd + Shift

Remove item(s) to the existing selection.



Toggle the selected state of item(s).



Clarify selection from a pop-up menu.

Ctrl + Shift

Cmd + Alt

Highlight the net of selected pads or tracks

The selection filter panel in the lower right corner of the Pcbnew window controls which types of objects can be selected with the mouse. Turning off selection of unwanted object types makes it easier to select items in a dense board. The "All items" checkbox is a shortcut to turn the other items on and off. The "Locked items" checkbox is independent of the rest, and controls whether or not items that have been locked can be selected. You can right-click any object type in the selection filter to quickly change the filter to only allow selecting that type of object.

When a connected copper item is selected, you can expand the selection to other copper items of the same net using the Expand Selection command in the right-click context menu, or with the U hotkey by default. The first time you run this command, the selection will be expanded to the nearest pad. The second time, the selection will be expanded to all connected items on all layers.

Cross-probing from the schematic

KiCad allows bi-directional cross-probing between the schematic and the PCB. There are several different types of cross-probing.

Selection cross-probing is always enabled. Selecting a symbol in the schematic will select the corresponding footprint in the PCB (if one exists) and vice-versa. Selecting a pin in the schematic will select the corresponding pad in the PCB and vice-versa. By default, cross-probing will result in the display centering on the cross-probed item and zooming to fit. This behavior can be disabled in the Display Options section of the Preferences dialog.

Highlight cross-probing is enabled when the Highlight Net tool is active in both the schematic editor and the PCB editor. Highlighting a net in one editor will cause the corresponding net to be highlighted in the other. Highlighting a bus in the schematic editor will cause all nets in the bus to be highlighted in the PCB editor. Highlight cross-probing can be disabled in the Display Options section of the Preferences dialog.

Left toolbar display controls

The left toolbar provides options to change the display of items in Pcbnew.


Turns grid display on/off.

Note: by default, hiding the grid will disable grid snapping. This behavior can be changed in the Display Options section of Preferences.

polar coord

Switch between polar and Cartesian coordinate display in the status bar.

unit inch

unit mil

unit mm

Display/entry of coordinates and dimensions in inches, mils, or millimeters.

cursor shape

Switches between full-screen and small editing cursor (crosshairs).

general ratsnest

Turns the ratsnest display on/off.

curved ratsnest

Switches between straight and curved ratsnest lines.

show zone

Show zone filled areas.

show zone disable

Show zone outlines only.

show zone outline only

Show zone filled areas as outlines.

pad sketch

Switches display of pads between filled and outline mode.

via sketch

Switches display of vias between filled and outline mode.


Switches display of tracks between filled and outline mode.

contrast mode

Switches the non-active layer display mode between Normal and Dim.

Note: this button will be highlighted when the non-active layer display mode is either Dim or Hide. In both cases, pressing the button will change the layer display mode to Normal. The Hide mode can only be accessed via the controls in the Appearance Panel or via the hotkey Ctrl+H.

layers manager

Shows or hides the Appearance and Selection Filter panels on the right side of the editor.

Creating PCBs

Basic PCB concepts

A printed circuit board in KiCad is generally made up of footprints representing electronic components and their pads, nets defining how those pads connect to each other, tracks, vias, and filled zones that form the copper connections between pads in each net, and various graphic shapes defining the board edge, silkscreen markings, and any other desired information.

Pcbnew normally keeps the information about nets on a PCB synchronized with an associated schematic, but nets can also be created and edited directly within Pcbnew.


Pcbnew is capable of creating printed circuit boards with up to 32 copper layers, 14 technical layers (silkscreen, solder mask, component adhesive, solder paste, etc) and 13 general-purpose drawing layers.

The internal measurement resolution of all objects in Pcbnew is 1 nanometer, and measurements are stored as 32-bit integers. This means it is possible to create boards up to appproximately 4 meters by 4 meters.

KiCad currently supports one board file per project / schematic.

Starting from a schematic

Creating a board from a schematic is the recommended workflow for KiCad. When you create a new project, KiCad will generate an empty board file with the same name as the project. To start designing the board after you have created a schematic, simply open the board file. You can do this either from the KiCad project manager, or by clicking the "Open PCB in board editor" button in Eeschema.

Starting from scratch

It is also possible to create a board with no matching schematic, although this workflow has some limitations and is not recommended for most users. To do this, you must start Pcbnew standalone (not from the KiCad project manager). Before beginning your design, it is a good idea to save the board file, which will also create a project file to store board settings. Use "Save As…​" from the File menu to choose where to save your board file. A project file with the same name will be created in the same location you choose to save the board file in.

Board setup

Before beginning your board design, use the Board Setup dialog to configure the basic parameters of the board. To open Board Setup, click the icon in the top toolbar or choose "Board Setup…​" from the File menu.

TODO: Add screenshot of Board Setup

Configuring board stackup

Configuring default text and graphic settings

Configuring design rules

Design rules control the behavior of the interactive router, the filling of copper zones, and the design rule checker. Design rules can be modified at any time, but it is recommended to establish all known design rules at the beginning of the board design process.


Basic constraints are configured in the Constrants section of the Board Setup dialog. Constraints in this section apply to the entire board, and should be set to the values recommended by your board manufacturer.

board setup constraints
Pre-defined Sizes
TODO: Write this section
Net Classes
TODO: Write this section
Custom Rules
TODO: Write this section

See Custom Design Rules in the Advanced Topics chapter for more information

Violation Severity
TODO: Write this section

Editing a board

Placement and drawing operations

Placement and drawing tools are located in the right toolbar. When a tool is activated, it stays active until a different tool is selected, or the tool is canceled with the Esc key. The selection tool is always activated when any other tool is canceled.

Some toolbar buttons have more than one tool available in a palette. These tools are indicated with a small arrow in the lower-right corner of the button: pcbnew palette buttons

To show the palette, you can click and hold the mouse button on the tool, or click and drag the mouse. The palette will show the most recently used tool when it is closed.


Selection tool (the default tool).

net highlight

Net highlight tool: selecting pads, tracks, or vias with this tool will highlight the associated net while this tool is active. Clicking on empty space will remove the highlight.

tool ratsnest

Local ratsnest tool: when the board ratsnest is hidden, selecting footprints with this tool will show the ratsnest for the selected footprint only. Selecting the same footprint again will hide its ratsnest. The local ratsnest setting for each footprint will remain in effect even after the local ratsnest tool is no longer active.


Footprint placement tool: click on the board to open the footprint chooser, then click again after choosing a footprint to confirm its location.

add tracks

ps diff pair

Route tracks / route differential pairs: These tools activate the interactive router and allow placing tracks and vias. The interactive router is described in more detail below.

add via

Add vias: allows placing vias without routing tracks.

Vias placed on top of tracks using this tool will take on the net of the closest track segment, and will become part of that track (the via net will be updated if the pads connected to the tracks are updated).

Vias placed anywhere else will take on the net of a copper zone at that location, if one exists. These vias will not automatically take on a new net if the net of the copper zone is changed.

mw add line

Add microwave shapes: these tools allow creation of some types of high-frequency circuit elements such as stubs, arcs, and serpentines.

add zone

Add filled zone: Click to set the start point of a zone, then configure its properties before drawing the rest of the zone outline. Zone properties are described in more detail below.

add keepout area

Add rule area: Rule areas, formerly known as keepouts, can restrict the placement of items and the filling of zones, and can also define named areas to apply specific custom design rules to.

add line

Draw lines.

Note: Lines are graphical objects and are not the same as tracks placed with the Route Tracks tool. Graphical objects cannot be assigned to a net.

add arc

Draw arcs: pick the center point of the arc, then the start and end points.

add rectangle

Draw rectangles. Rectangles can be filled or outlines.

add circle

Draw circles. Circles can be filled or outlines.

add graphical polygon

Draw graphical polygons. Polygons can be filled our outlines.

Note: Filled graphical polygons are not the same as filled zones: graphical polygons cannot be assigned to a net and will not keep clearance from other items.


Add text.

add aligned dimension

add orthogonal dimension

add center dimension

add leader

Add dimensions. Dimension types are described in more detail below.

add pcb target

Add layer alignment mark.


Deletion tool: click objects to delete them.

set origin

Set drill/place origin. Used for fabrication outputs.

grid select axis

Set grid origin.


When moving, dragging, and drawing board elements, the grid, pads, and other elements can have snapping points depending upon the settings in the user preferences. In complex designs, snap points can be so close together that it makes the current tool action difficult. Both grid and object snapping can be disabled while moving the mouse by using the modifier keys in the table below.

Modifier Key Effect


Disable grid snapping.


Disable object snapping.

Editing object properties

All objects have properties that are editable in a dialog. Use the hotkey E or select Properties from the right-click context menu to edit the properties of selected item(s). You can only open the properties dialog if all the items you have selected are of the same type. To edit the properties of different types of items at one time, see the section below on bulk editing tools.

Working with footprints

TODO: Write this section - covers footprint properties, updating from library, etc

Working with pads

TODO: Write this section - covers pad properties

Working with zones

TODO: Write this section

Graphical objects

Graphical objects (lines, arcs, rectangles, circles, polygons, and text) can exist on any layer but cannot be assigned to a net. Rectangles, circles, and polygons can be set to be filled or outlines in their propeties dialogs. The line width property will control the width of the outline even for filled shapes. Line width can be set to 0 for filled shapes to disable the outline.

Board outlines (Edge Cuts)

Pcbnew uses graphical objects on the Edge.Cuts layer to define the board outline. The outline must be a continuous (closed) shape, but can be made up of different types of graphical object such as lines and arcs, or be a single object such as a rectangle or polygon. If no board outline is defined, or the board outline is invalid, some functions such as the 3D viewer and some design rule checks will not be functional.


TODO: Write this section

Routing traces

TODO: Write this section

Interactive router settings

The interactive router settings can be accessed through the Route menu, or by right-clicking on the Route Tracks button in the toolbar. These settings control the router behavior when routing tracks as well as when dragging existing tracks.

pcbnew interactive router settings
Setting Description


Highlight collisions: disables most router features and allows manual placement of tracks and vias, with DRC violations (collisions) highlighted.

Shove: moves other tracks and vias out of the way of the tracks being routed to avoid DRC violations.

Walk around: prevents placing tracks and vias in locations that would cause a DRC violation, allowing you to "walk around" existing tracks and vias.

Free angle mode

Allows routing tracks at any angle, instead of just at 45-degree increments. This option is only available if the router mode is set to Highlight collisions.

Jump over obstacles

In Shove mode, allows the router to attempt to move colliding tracks behind solid obstacles (such as pads).

Remove redundant tracks

Automatically removes loops created in the currently-routed track, keeping only the most recently routed section of the loop.

Optimize pad connections

When this setting is enabled, the router attempts to avoid acute angles and other undesirable routing when exiting pads and vias.

Smooth dragged segments

When dragging tracks, attempts to combine track segments together to minimize direction changes.

Allow DRC violations

In Highlight collisions mode, allows placing tracks and vias that violate DRC rules. Has no effect in other modes.

Optimize track being dragged

Attempts to simplify tracks while they are being dragged.

Use mouse path to set track posture

Attempts to pick the track posture based on the mouse path from the routing start location. If the mouse moves mostly diagonally from the start location, the posture will be set to a diagonal start, and if the mouse moves mostly horizontally or vertically, the posture will be set to a vertical start. The posture guess is “locked” when the mouse moves far away from the routing start location, and can be “unlocked” by moving back to the start location.

Note: Setting the posture manually using the Set Track Posture hotkey (/) will disable the mouse path posture algorithm until the router is restarted.

Fix all segments on click

When enabled, clicking while routing will fix the position of all the track segments that have been routed, including the segment that ends at the mouse cursor. A new segment will be started from the mouse cursor location. When disabled, the last segment (the one that ends at the mouse cursor) will not be fixed in place and can be adjusted by further mouse movement.

Differential pairs

TODO: Write this section

Forward and back annotation

TODO: Write this section

Geographical re-annotation

TODO: Write this section


Most objects can be locked through their properties dialogs or by using the right-click context menu. Locked objects cannot be selected unless the "Locked items" checkbox is enabled in the selection filter. Attempting to move locked items will result in a warning dialog:

pcbnew locked items dialog

Selecting "Override Locks" in this dialog will allow moving the locked items. Selecting "OK" will allow you to move any unlocked items in the selection; leaving the locked items behind. Selecting "Do not show again" will remember your choice for the rest of your session.

Bulk editing tools

TODO: Write this section

Cleanup tools

TODO: Write this section

Inspecting a board

Measurement tool

TODO: Write this section

Design rule checking

TODO: Write this section

Clearance and constraint resolution

TODO: Write this section

3D viewer

TODO: Write this section

Net inspector

TODO: Write this section

Generating outputs

Fabrication outputs

TODO: Write this section


TODO: Write this section

Exporting files

TODO: Write this section NOTE: Bring IDF exporter docs in to here

Footprints and footprint libraries

Managing footprint libraries

TODO: Write this section

Creating and editing footprints

TODO: Write this section

Custom pad shapes

Footprint attributes

Mention net ties here

Footprint wizards

For more information about creating new footprint wizards, see the Scripting section of the Advanced Topics chapter.

Advanced topics

Configuration and Customization

Pcbnew has a variety of preferences that can be configured through the Preferences dialog. Like all parts of KiCad, the preferences for Pcbnew are stored in the user configuration directory, and are independent between KiCad minor versions to allow multiple versions to run side-by-side with independent preferences.

The first sections of the Preferences dialog (Common, Mouse and Touchpad, and Hotkeys) are shared between all KiCad programs. These sections are described in detail in the KiCad manual under the "Common preferences" section. Note that even though the Hotkeys section is shared between all programs, there are many Pcbnew-specific hotkeys that only appear in the list when Pcbnew is running.

Display options

pcbnew preferences display

Grid style: Controls how the alignment grid is drawn.

Grid thickness: Controls how thick grid lines or dots are drawn.

Min grid spacing: Controls the minimum distance, in pixels, between two grid lines. Grid line that violate this minimum spacing will not be drawn, regardless of the current grid setting.

Snap to grid: Controls when drawing and editing operations will be snapped to coordinates on the active grid. "Always" will enable snapping even when the grid is hidden; "When grid shown" will enable snapping only when the grid is visible.

Grid snapping can be temporarily disabled by holding down Shift.

Cursor shape: Controls whether the editing cursor is drawn as a small crosshair or a full-screen crosshair (a set of lines covering the entire drawing canvas). The editing cursor shows where the next drawing or editing action will occur, and will be snapped to a grid location if snapping is enabled.

Always show crosshairs: Controls whether the editing cursor is shown all the time, or only when an editing or drawing tool is active.

Net names: Controls whether or not net name labels are drawn on copper objects. These labels are guides for editing only, and do not appear in fabrication outputs.

Show pad numbers: Controls whether or not pad number labels are drawn on footprint pads.

Show pad <no net> indicator: Controls whether or not pads with no net are indicated with a special marker.

Track clearance: Controls whether or not clearance outlines around tracks and vias are shown. Clearance outlines are shown as thin shapes around objects that indicate the minimum clearance to other objects, as defined by constraints and design rules.

Show pad clearance: Controls whether or not clearance outlines around pads are shown.

Center view on cross-probed items: When both Eeschema and Pcbnew are running, controls whether clicking a component or pin in Eeschema will center the Pcbnew view on the corresponding footprint or pad.

Zoom to fit cross-probed items: Controls whether the view will be zoomed to show a cross-probed footprint or pad.

Highlight cross-probed nets: Controls whether or not nets highlighted in Eeschema will be highlighted in Pcbnew when the highlight tool is activated in both tools.

Editing options

pcbnew preferences editing

Lock pads of newly added footprints: Controls whether or not the pads of footprints will default to locked or unlocked (editable).

Flip board items L/R: Controls the direction board items will be flipped when moving them between the top and bottom layers.

Limit graphic lines to H, V and 45 degrees: Controls whether lines drawn with the graphic drawing tools can take on any angle. Note that this only affects drawing new lines: lines can be edited to take on any angle.

Magnetic points: This section controls object snapping, also called magnetic points. Object snapping takes precedence over grid snapping when it is enabled. Object snapping only works to objects on the active layer. Hold Alt to temporary disable object snapping.

Snap to pads: Controls when the editing cursor will snap to pad origins.

Snap to tracks: Controls when the editing cursor will snap to track segment endpoints.

Snap to graphics: Controls when the editing cursor will snap to graphic shape points.

Always show selected ratsnest: When enabled, the ratsnest for a selected footprint will always be shown even if the global ratsnest is hidden.

Show ratsnest with curved lines: Controls whether ratsnest lines are drawn straight or curved.

Show page limits: Controls whether or not the page boundary is drawn as a rectangle.

Mouse drag track behavior: Controls the action that will occur when you drag a track segment with the mouse: "Move" will move the track segment independent of any others. "Drag" will invoke the push-and-shove router to drag the track, respecting design rules and keeping other track segments attached.


pcbnew preferences colors

Pcbnew supports switching between different color themes to match your preferences. Kicad 6.0 comes with two built-in color themes: "KiCad Default" is a new theme designed to have good contrast and balance for most cases, and is the default for new installations. "KiCad Classic" is the default theme from KiCad 5.1 and earlier versions. Both of these built-in themes cannot be modified, but you can create new themes to customize the look of Pcbnew as well as install themes made by other users.

Color themes are stored in JSON files located in the colors subdirectory of the KiCad configuration directory. The "Open Theme Folder" button will open this location in your system file manager, making it easy to manage your installed themes. To install a new theme, place it in this folder and restart KiCad. The new theme will be available from the drop-down list of color themes if the file is a valid color theme file.

To create a new color theme, choose New Theme…​ from the drop-down list of color themes. Enter a name for your theme, and then begin editing colors. The colors in the new theme will be copied from whatever theme was selected before you created the new theme.

To change a color, double-click or middle-click the color swatch in the list. The "Reset to Default" button will reset that color to its corresponding entry in the "KiCad Default" color theme.

Color themes are saved automatically; all changes are reflected immediately when you close the Preferences dialog. The window on the right side of the dialog shows a preview of how the selected theme will look.

Action plugins

TODO: Write this section

Origin & axes

pcbnew preferences origin axes

Display origin: Determines which coordinate origin is used for coordinate display in the editing canvas. The page origin is fixed at the corner of the page. The drill/place file origin and the grid origin can be moved by the user.

X axis: Controls whether X-coordinates increase to the right or to the left.

Y axis: Controls whether Y-coordinates increase upwards or downwards.

Custom design rules

The custom design rule language is based on s-expressions and allows you to create design constraints that are not possible with the built-in constraints. Each design rule generally contains an expression defining what objects to match, adn a constraint defining the rule to be applied to the matched objects.

Custom rule syntax

TODO: Write this section

Custom design rule examples

TODO: Write this section


Scripting allows you to automate tasks within KiCad using the Python language. It is possible to add functionality to Pcbnew through Python "action plugins" that can be added to the top toolbar. It is also possible to write standalone scripts that interact with KiCad files, for example, to generate fabrication outputs from a board file automatically.

This manual covers general scripting concepts. Users wishing to write or modify scripts should also use the Doxygen documentation located at

KiCad can be built with support for Python 2 or Python 3. Release builds of KiCad 6 and later will generally be built with Python 3 support, as Python 2 is no longer maintained.

Python script locations

TODO: fill this out with final 6.0 scripting locations for each platform

Action plugins

TODO: Write this section (how to install new action plugins)

Footprint wizards

The footprint wizards are a collection of python scripts that can be accessed from the Footprint Editor. If you invoke the footprint dialog you select a given wizard that allows you to see the footprint rendered, and you have some parameters you can edit.

If the plugins are not properly distributed to your system package, you can find the latest versions in the KiCad source tree at gitlab.

Using the scripting console

Pcbnew comes with a built-in Python console that can be used to inspect and interact with the board. To launch the console, use the py script icon in the top toolbar. The Pcbnew Python API is not automatically loaded, so to load it, type import pcbnew into the console. The command pcbnew.GetBoard() will then return a reference to the board currently loaded in Pcbnew, which can be inspected and modified through the console.

TODO: Document the other useful PyAlaMode functions

Writing external scripts

TODO: Write this section

Writing action plugins

TODO: Write this section

Actions reference

Below is a list of every available action in Pcbnew: a command that can be assigned to a hotkey. Hotkeys that are shared between all KiCad applications are listed in the KiCad manual and are not included here.

PCB Editor

Action Default Hotkey Description

Align to Bottom

Aligns selected items to the bottom edge

Align to Vertical Center

Aligns selected items to the vertical center

Align to Horizontal Center

Aligns selected items to the horizontal center

Align to Left

Aligns selected items to the left edge

Align to Right

Aligns selected items to the right edge

Align to Top

Aligns selected items to the top edge

Distribute Horizontally

Distributes selected items along the horizontal axis

Distribute Vertically

Distributes selected items along the vertical axis

Place Off-Board Footprints

Performs automatic placement of components outside board area

Place Selected Footprints

Performs automatic placement of selected components

Flip Board View

View board from the opposite side

Sketch Graphic Items

Show graphic items in outline mode

Decrease Layer Opacity


Make the current layer more transparent

Increase Layer Opacity


Make the current layer more transparent

Switch to Copper (B.Cu) layer


Switch to Inner layer 1

Switch to Inner layer 10

Switch to Inner layer 11

Switch to Inner layer 12

Switch to Inner layer 13

Switch to Inner layer 14

Switch to Inner layer 15

Switch to Inner layer 16

Switch to Inner layer 17

Switch to Inner layer 18

Switch to Inner layer 19

Switch to Inner layer 2

Switch to Inner layer 20

Switch to Inner layer 21

Switch to Inner layer 22

Switch to Inner layer 23

Switch to Inner layer 24

Switch to Inner layer 25

Switch to Inner layer 26

Switch to Inner layer 27

Switch to Inner layer 28

Switch to Inner layer 29

Switch to Inner layer 3

Switch to Inner layer 30

Switch to Inner layer 4

Switch to Inner layer 5

Switch to Inner layer 6

Switch to Inner layer 7

Switch to Inner layer 8

Switch to Inner layer 9

Switch to Next Layer


Switch to Previous Layer


Toggle Layer


Switch between layers in active layer pair

Switch to Component (F.Cu) layer


Net Inspector

Show the net inspector

Highlight Ratsnest

Show ratsnest of selected item(s)

Sketch Pads

Show pads in outline mode

Curved Ratsnest Lines

Show ratsnest with curved lines

Repair Board

Run various diagnostics and attempt to repair board

Show Appearance Manager

Show/hide the appearance manager

Show pad numbers

Show pad numbers

Scripting Console

Show the Python scripting console

Show Ratsnest

Show board ratsnest

Sketch Text Items

Show footprint texts in line mode

Sketch Tracks


Show tracks in outline mode

Sketch Vias

Show vias in outline mode

Wireframe Zones

Show only zone boundaries

Fill Zones

Show filled areas of zones

Sketch Zones

Show solid areas of zones in outline mode

Toggle Zone Display


Cycle between showing filled zones, wireframed zones and sketched zones

Automatically zoom to fit

Zoom to fit when changing footprint

Convert to Arc

Converts selected line segment to an arc

Convert to Rule Area

Creates a rule area from the selection

Convert to Lines

Creates graphic lines from the selection

Convert to Polygon

Creates a graphic polygon from the selection

Convert to Tracks

Converts selected graphic lines to tracks

Convert to Zone

Creates a copper zone from the selection

Design Rules Checker

Show the design rules checker window

Open in Footprint Editor


Opens the selected footprint in the Footprint Editor

Append Board…​

Open another board and append its contents to this board

Board Setup…​

Edit board setup including layers, design rules and various defaults

Clear Net Highlighting

Clear any existing net highlighting

Drill/Place File Origin

Place origin point for drill files and component placement files

Specctra DSN…​

Export Specctra DSN routing info


Create bill of materials from board

IPC-D-356 Netlist File…​

Generate IPC-D-356 netlist file

Drill Files (.drl)…​

Generate Excellon drill file(s)

Gerbers (.gbr)…​

Generate Gerbers for fabrication

Component Placement (.pos)…​

Generate component placement file(s) for pick and place

Footprint Report (.rpt)…​

Create report of all footprints from current board


Group the selected items so that they are treated as a single item

Enter Group

Enter the group to edit items

Leave Group

Leave the current group

Hide Net

Hide the ratsnest for the selected net

Highlight Net


Highlight all copper items of a net

Highlight Nets

Highlight all copper items of a net


Read netlist and update board connectivity

Specctra Session…​

Import routed Specctra session (*.ses) file


Prevent items from being moved and/or resized on the canvas

Add Footprint


Add a footprint

Add Layer Alignment Target

Add a layer alignment target

Remove Items

Remove items from group

Switch to Schematic Editor

Open schematic in Eeschema

Show Net

Show the ratsnest for the selected net

Toggle Last Net Highlight

Toggle between last two highlighted nets

Toggle Lock


Lock or unlock selected items

Switch Track Width to Previous


Change track width to previous pre-defined size

Switch Track Width to Next


Change track width to next pre-defined size


Ungroup any selected groups


Allow items to be moved and/or resized on the canvas

Decrease Via Size


Change via size to previous pre-defined size

Increase Via Size


Change via size to next pre-defined size

Duplicate Zone onto Layer…​

Duplicate zone outline onto a different layer

Merge Zones

Merge zones

Change Footprint…​

Assign a different footprint from the library

Change Footprints…​

Assign different footprints from the library

Cleanup Graphics…​

Cleanup redundant items, etc.

Cleanup Tracks & Vias…​

Cleanup redundant items, shorting items, etc.

Edit Text & Graphics Properties…​

Edit Text and graphics properties globally across board

Edit Track & Via Properties…​

Edit track and via properties globally across board

Global Deletions…​

Delete tracks, footprints and graphic items from board

Remove Unused Pads…​

Remove or restore the unconnected inner layers on through hole pads and vias

Swap Layers…​

Move tracks or drawings from one layer to another

Update Footprint…​

Update footprint to include any changes from the library

Update Footprints from Library…​

Update footprints to include any changes from the library

Clearance Resolution…​

Show clearance resolution for the active layer between two selected objects

Constraints Resolution…​

Show constraints resolution for the selected object

Show Board Statistics

Shows board statistics

Add Aligned Dimension


Add an aligned linear dimension

Draw Arc


Draw an arc

Switch Arc Posture


Switch the arc posture

Add Center Dimension

Add a center dimension

Draw Circle


Draw a circle

Close Outline

Close the in progress outline

Decrease Line Width


Decrease the line width

Delete Last Point


Delete the last point added to the current item

Draw Graphic Polygon


Draw a graphic polygon

Increase Line Width


Increase the line width

Add Leader

Add a leader dimension

Draw Line


Draw a line

Limit Lines to 45 deg

Limit graphic lines to H, V and 45 degrees

Add Orthogonal Dimension

Add an orthogonal dimension

Place Imported Graphics


Draw Rectangle

Draw a rectangle

Add Rule Area


Add a rule area (keepout)

Place the Footprint Anchor


Set the coordinate origin point (anchor) of the footprint

Add a Similar Zone


Add a zone with the same settings as an existing zone

Add Text


Add a text item

Add Vias


Add free-standing vias

Add Filled Zone


Add a filled zone

Add a Zone Cutout


Add a cutout area of an existing zone

Get and Move Footprint


Selects a footprint by reference designator and places it under the cursor for moving

Change Track Width

Updates selected track & via sizes

Create Array…​


Create array

Delete Full Track


Deletes selected item(s) and copper connections

Duplicate and Increment


Duplicates the selected item(s), incrementing pad numbers

Fillet Tracks

Adds arcs tangent to the selected straight track segments

Change Side / Flip


Flips selected item(s) to opposite side of board


Mirrors selected item

Move Exactly…​


Moves the selected item(s) by an exact amount



Displays item properties dialog

Rotate Counterclockwise


Rotates selected item(s) counterclockwise

Rotate Clockwise


Rotates selected item(s) clockwise

Copy with Reference

Copy selected item(s) to clipboard with a specified starting point



Moves the selected item(s)

Move with Reference

Moves the selected item(s) with a specified starting point

Auto-finish Track


Automagically finishes laying the current track.

Break Track

Splits the track segment into two segments connected at the cursor position.

Custom Track/Via Size…​


Shows a dialog for changing the track width and via size.

Route Differential Pair


Route differential pairs

Differential Pair Dimensions…​

Open Differential Pair Dimension settings

Drag (45 degree mode)


Drags the track segment while keeping connected tracks at 45 degrees.

Drag (free angle)


Drags the nearest joint in the track without restricting the track angle.

Finish Track


Stops laying the current track.

Router Highlight Mode

Switch router to highlight mode

Break Track

Splits the track segment into two segments connected at the cursor position.

Place Blind/Buried Via


Adds a blind or buried via at the end of currently routed track.

Place Microvia


Adds a microvia at the end of currently routed track.

Place Through Via


Adds a through-hole via at the end of currently routed track.

Select Layer and Place Blind/Buried Via…​


Select a layer, then add a blind or buried via at the end of currently routed track.

Select Layer and Place Through Via…​


Select a layer, then add a through-hole via at the end of currently routed track.

Set Layer Pair…​

Change active layer pair for routing

Interactive Router Settings…​


Open Interactive Router settings

Router Shove Mode

Switch router to shove mode

Route Single Track


Route tracks

Switch Track Posture


Switches posture of the currently routed track.

Switch Corner Rounding


Switches the corner type of the currently routed track.

Undo last segment


Stops laying the current track.

Router Walkaround Mode

Switch router to walkaround mode

Deselect All Tracks in Net

Deselects all tracks & vias belonging to the same net.

Filter Selected Items…​

Remove items from the selection by type

Select/Expand Connection


Selects a connection or expands an existing selection to junctions, pads, or entire connections

Select All Tracks in Net

Selects all tracks & vias belonging to the same net.


Selects all footprints and tracks in the schematic sheet

Items in Same Hierarchical Sheet

Selects all footprints and tracks in the same schematic sheet

Decrease Amplitude


Decrease meander amplitude by one step.

Increase Amplitude


Increase meander amplitude by one step.

End Track


Stops laying the current meander.

Length Tuning Settings…​


Sets the length tuning parameters for currently routed item.

Decrease Spacing


Decrease meander spacing by one step.

Increase Spacing


Increase meander spacing by one step.

New Track


Starts laying a new track.

Tune length of a differential pair


Tune skew of a differential pair


Tune length of a single track


Add Microwave Polygonal Shape

Create a microwave polygonal shape from a list of vertices

Add Microwave Gap

Create gap of specified length for microwave applications

Add Microwave Line

Create line of specified length for microwave applications

Add Microwave Stub

Create stub of specified length for microwave applications

Add Microwave Arc Stub

Create stub (arc) of specified size for microwave applications

Footprint Checker

Show the footprint checker window

Copy Footprint

Create Footprint…​

Create a new footprint using the Footprint Wizard

Cut Footprint

Delete Footprint from Library

Edit Footprint

Show selected footprint on editor canvas

Export Footprint…​

Footprint Properties…​

Edit footprint properties

Import Footprint…​

New Footprint…​


Create a new, empty footprint

Paste Footprint

Show Footprint Tree

Toggles the footprint tree visibility

Paste Default Pad Properties to Selected

Replace the current pad’s properties with those copied earlier

Copy Pad Properties to Default

Copy current pad’s properties

Push Pad Properties to Other Pads…​

Copy the current pad’s properties to other pads

Default Pad Properties…​

Edit the pad properties used when creating new pads

Renumber Pads…​

Renumber pads by clicking on them in the desired order

Edit Pad as Graphic Shapes


Ungroups a custom-shaped pad for editing as individual graphic shapes

Add Pad

Add a pad

Finish Pad Edit


Regroups all touching graphic shapes into the edited pad

Create Corner


Create a corner

Remove Corner

Remove corner

Position Relative To…​


Positions the selected item(s) by an exact amount relative to another

Geographical Reannotate…​

Reannotate PCB in geographical order


Fill zone(s)

Fill All


Fill all zones


Unfill zone(s)

Unfill All


Unfill all zones

3D Viewer

Action Default Hotkey Description

Add Floor

Adds a floor plane below the board (slow)


Render with improved quality on final render (slow)

Toggle SMD 3D models


Toggle 3D models with 'Surface mount' attribute

Toggle Through Hole 3D models


Toggle 3D models with 'Through hole' attribute

Toggle Virtual 3D models


Toggle 3D models with 'Virtual' attribute

Flip Board

Flip the board view

Home view


Home view

CAD Color Style

Use a CAD color style based on the diffuse color of the material

Use Diffuse Only

Use only the diffuse color property from model 3D model file

Use All Properties

Use all material properties from each 3D model file

Move board Down


Move board Down

Move board Left


Move board Left

Move board Right


Move board Right

Move board Up


Move board Up

No 3D Grid

No 3D Grid

Center pivot rotation


Center pivot rotation (middle mouse click)


Apply Screen Space Ambient Occlusion and Global Illumination reflections on final render (slow)

Procedural Textures

Apply procedural textures to materials (slow)

Render Shadows

Render Shadows

Reset view


Reset view

Rotate 45 degrees over Z axis


Rotate X Clockwise

Rotate X Clockwise

Rotate X Counterclockwise

Rotate X Counterclockwise

Rotate Y Clockwise

Rotate Y Clockwise

Rotate Y Counterclockwise

Rotate Y Counterclockwise

Rotate Z Clockwise

Rotate Z Clockwise

Rotate Z Counterclockwise

Rotate Z Counterclockwise

3D Grid 10mm

3D Grid 10mm

3D Grid 1mm

3D Grid 1mm

3D Grid 2.5mm

3D Grid 2.5mm

3D Grid 5mm

3D Grid 5mm

Show 3D Axis

Show 3D Axis

Show Model Bounding Boxes

Show Model Bounding Boxes


Render materials with reflective properties on final render (slow)


Render materials with refractive properties on final render (slow)

Toggle adhesive display

Toggle display of adhesive layers

Toggle board body display

Toggle board body display

Toggle comments display

Toggle display of comments and drawings layers

Toggle ECO display

Toggle display of ECO layers

Toggle orthographic projection

Enable/disable orthographic projection

Toggle realistic mode

Toggle realistic mode

Toggle silkscreen display

Toggle display of silkscreen layers

Toggle solder mask display

Toggle display of solder mask layers

Toggle solder paste display

Toggle display of solder paste layers

Toggle zone display

Toggle zone display

View Back


View Back

View Bottom


View Bottom

View Front


View Front

View Left


View Left

View Right


View Right

View Top


View Top