PCB Editor

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.

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.

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 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.

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.

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.

The tool has several options to control its behavior.

There are two sections of Board Setup used to configure the stackup and layers of the board. The Board Editor Layers section is used to enable or disable technical (non-copper) layers, and give custom names to layers if desired. The Physical Stackup section is used to configure the number of copper layers, as well as the physical parameters of the copper and dielectric layers such as thickness and material type.

To configure the board stackup, start on the Physical Stackup section:

Set the number of copper layers in the upper left corner and then enter the physical parameters of the stackup if desired. These parameters may be left at their default values, but note that the board thickness value will be used when exporting a 3D model of the board. If you plan to use this feature, it is a good idea to ensure that the stackup thickness is correct.

Next, if desired, use the Board Editor Layers section to rename layers or hide non-copper layers that you will not be using in the design. For example, if you will not use a back silkscreen on the design, uncheck the box next to the B.Silkscreen layer.

Some additional board stackup settings are found on the Board Finish and Solder Mask/Paste sections of the Board Setup dialog. The Board Finish section has settings for defining the copper finish and special features such as castellations or edge plating. Note that these settings only impact the board attributes output as part of Gerber job files at this time.

The Solder Mask/Paste section allow global adjustment of the clearance (positive or negative) between the copper shapes and solder mask / solder paste shapes of pads on the board. These values will be added to any clearance overrides set on individual footprints or pads. Positive clearance values will result in the shape of the solder mask or paste opening being larger than the copper shape. Negative clearance values will result in the opening being smaller than the copper shape.

The Text & Graphics Defaults section of the Board Setup dialog can be used to configure the properties that will be used for new text and graphic shapes that are placed on the board.

Line thickness, text size, and text appearance can be configured for the six different categories of layers shown in the dialog. Additionally, the properties for dimension objects can be configured for all layers. For more details about dimension properties, see the Dimensions section below.

Text replacement variables can be created in the Text Variables section. These variables allow you to substitute the variable name for any text string. This substitution happens anywhere the variable name is used inside the variable replacement syntax of ${VARIABLENAME}.

For example, you could create a variable named VERSION and set the text substitution to 1.0. Now, in any text object on the PCB, you can enter ${VERSION} and KiCad will substitute 1.0. If you change the substitution to 2.0, every text object that includes ${VERSION} will be updated automatically. You can also mix regular text and variables. For example, you can create a text object with the text Version: ${VERSION} which will be substituted as Version: 1.0.

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 we recommend that you establish all known design rules at the beginning of the board design process.

The right toolbar can be used to create lines (, default hotkey Ctrl+Shift+L), arcs (, default hotkey Ctrl+Shift+A), rectangles (), circles (, default hotkey Ctrl+Shift+C), and polygons (, default hotkey Ctrl+Shift+P).

Rectangles, circles, and polygons can be filled shapes or outlines. The line width option controls the width of the outline. The outline width extends on both sides of the "ideal" shape of the graphic object. For example, a graphic circle that is defined to have 2mm radius and 0.2mm line width will consist of a torus with an outer radius of 2.2mm and inner radius of 1.8mm. If the filled shape option is enabled and the line width is set to 0, the shape will be a filled circle with 2mm radius.

Graphical text may be placed by using the () icon in the right toolbar or by keyboard shortcut Ctrl+Shift+T. Click to place the text origin, and then edit the text and its properties in the dialog that will appear:

Text may be placed on any layer, but note that text on copper layers cannot be associated with a net and cannot form connections to tracks or pads. Copper zones will fill around the rectangular bounding box of text objects.

KiCad 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.

Override value: When enabled, you may enter a measurement value directly into the Value field that will be used instead of the actual measured value.

Prefix: Any text entered here will be shown before the measurement value.

Suffix: Any text entered here will be shown after the measurement value.

Layer: Selects which layer the dimension object exists on.

Units: Selects which units to display the measured value in. Automatic units will result in the dimension units changing when the display units of the board editor are changed.

Units format: Select from several built-in styles of unit display.

Precision: Select how many digits of precision to display.

Most of the dimension text options are identical to those options available for other graphical text objects (see the Graphical Objects section above). Some specific options for dimension text are also available:

Position mode: Choose whether to position the dimension text manually, or to automatically keep it aligned with the dimension measurement lines.

Keep aligned with dimension: When enabled, the orientation of the dimension text will be adjusted automatically to keep the text parallel with the measurement axis.

Line thickness: Sets the thickness of the graphical lines that make up a dimension’s shape.

Extension line offset: Sets the distance from the measurement point to the start of the extension lines.

Arrow length: Sets the length of the arrow segments of the dimension’s shape.

Value: Enter the text to show at the end of the leader line.

Text frame: Select the desired border around the text (circle, rectangle, or none).

When routing in H/V/45 mode, the posture refers to how a set of two track segments connect two points that cannot be reached by a single H/V/45-degree segment. In such a case, the points will be connected by one horizontal or vertical segment and one diagonal (45-degree) segment. The posture refers to the order of these segments: whether the horizontal/vertical segment or the diagonal segment comes first.

KiCad’s router attempts to pick the best posture automatically based on a number of factors. In general, the router will attempt to minimize the number of corners in a route, and will avoid "bad" corners such as acute angles whenever possible. When routing from or to a pad, KiCad will choose the posture that lines up the route with the longest edge of the pad.

In some cases, KiCad cannot guess the posture you intend correctly. To switch the posture of the track while routing, use the Switch Track Posture command (hotkey /).

In situations where there is no obvious "best" posture (for example, when starting a route from a via), KiCad will use the movement of your mouse cursor to select the posture. If you would like the route to begin with a straight (horizontal or vertical) segment, move the mouse away from the starting location in a mostly horizontal or vertical direction. If you would like the route to begin diagonally, move in a diagonal direction. Once the cursor is a sufficient distance away from the routing start location, the posture is "locked" and will no longer change unless the cursor is brought back to the starting location. Detection of posture from the movement of the mouse cursor can be disabled in the Interactive Router Settings dialog as described below.

KiCad’s router can place tracks with either sharp or rounded (arc) corners when routing in H/V/45 mode. To switch between sharp and rounded corners, use the Track Corner Mode command (hotkey Ctrl+/). When routing with rounded corners, each routing step will place either a straight segment, a single arc, or both a straight segment and an arc. The track posture determines whether the arc or the straight segment will be placed first.

Track corners can also be rounded after routing by using the Fillet Tracks command after selecting the desired tracks.

The width of the track being routed is determined in one of three ways: if the routing start point is the end of an existing track and the button on the top toolbar is enabled, the width will be set to the width of the existing track. Otherwise, if the track width dropdown in the top toolbar is set to "use netclass width", the width will be taken from the netclass of the net being routed (or from any custom design rules that specify a different width for the net, such as inside a neckdown area). Finally, if the track width dropdown is set to one of the pre-defined track sizes configured in the Board Setup dialog, this width will be used.

KiCad’s router supports a single track width for the active route. In other words, to change widths in the middle of a track, you must end the route and then restart a new route from the end of the previous route. To change the width of the active route, use the hotkeys W and Shift+W to step through the track widths configured in the Board Setup dialog.

While routing tracks, switching layers will insert a through via at the end of the current (unfixed) track. Once you place the via, routing will continue on the new layer. There are several ways to select a new layer and insert a via:

The size of the via will be taken from the active Via Size setting, accessible from the drop-down in the top toolbar or the Increase Via Size (') and Decrease Via Size (\) hotkeys. Much like track width, when the via size is set to "use netclass sizes", the via sizes configured in the Net Classes section of the Board Setup will be used (unless overridden by a custom design rule).

If microvias or blind/buried vias are enabled in the Constraints section of the Board Setup dialog, these vias can be placed while routing. Use the hotkey Ctrl+V to place a microvia and Alt+Shift+V to place a blind/buried via. Microvias may only be placed such that they connect one of the outer copper layers to an adjacent layer. Blind/buried vias may be placed on any layer.

Vias placed by the router are considered to be part of a routed track. This means that the via net can be updated automatically (just like track nets can), for example when updating the PCB from the schematic changes the net name of the track. In some cases this may not be desired, such as when creating stitching vias. The automatic update of via nets can be disabled for specific vias by turning off the "automatically update via nets" checkbox in the via properties dialog. Vias placed with the Add Free-standing Vias tool are created with this setting disabled.

Differential pairs in KiCad are defined as nets with a common base name and a positive and negative suffix. KiCad supports using + and -, or P and N as the suffix. For example, the nets USB+ and USB- form a differential pair, as do the nets USB_P and USB_N. In the first example, the base name is USB, and USB_ in the second. The suffix styles cannot be mixed: the nets USB+ and USB_N do not form a differential pair. Make sure you name your differential pair nets accordingly in the schematic in order to allow use of the differential pair router in the PCB editor.

To route a differential pair, click the Route Differential Pairs icon (from the drawing toolbar or from the top toolbar under Route) or use the hotkey 6. Click on a pad, via, or the end of an existing differential pair track to start routing. You can start routing from either the positive or negative net of a differential pair.

The differential pair router will attempt to route the pair of tracks with a gap taken from the design rules (differential pair gap can be configured in the Net Classes section of the Board Setup dialog, or by using custom design rules). If the starting or ending location of the route is a different distance apart from the configured gap, the router will create a short "fan out" section to minimize the length of track where the differential pair is not coupled.

When switching layers or using the Place Via (V) action, the differential pair router will create two vias next to each other. These vias will be placed as close as possible to each other while respecting the design rules for copper and hole-to-hole clearance.

After tracks have been routed, they can be modified by moving or dragging, or deleted and re-routed. When a single track segment is selected, the hotkey U can be used to expand the selection to all connected track segments. The first press of U will select track segments between the nearest junctions with pads or vias. The second press of U will expand the selection again to include all track segments connected to the selected track on all layers. Selecting tracks with this technique can be used to quickly delete an entire routed net.

There are two different drag commands that can be used to modify a track segment. The Drag (45-degree mode) command, hotkey D, is used to drag tracks using the router. If the router mode is set to Shove, dragging with this command will shove nearby tracks. If the router mode is set to Walk Around, dragging with this command will walk around or stop at obstacles. The Drag Free Angle command, hotkey G, is used to split a track segment into two and drag the new corner to any location. Drag Free Angle behaves like the Highlight Collisions router mode: obstacles will not be avoided or shoved, only highlighted.

The Move command (hotkey M) can also be used on track segments. This command will pick up the selected track segments, ignoring any attached track segments or vias that are not selected. No DRC checking is done when moving tracks using the Move command.

It is possible to re-route tracks attached to footprints while moving the footprints. To do so, use the drag command (D) with a footprint selected. Any tracks that end at one of the footprint’s pads will be dragged along with the footprint. This feature has some limitations: it only operates in Highlight Collisions mode, so the tracks attached to footprints will not walk around obstacles or shove nearby tracks out of the way. Additionally, only tracks that end at the origin of the footprint’s pads will be dragged. Tracks that simply pass through the pad or that end on the pad at a location other than the origin will not be dragged.

It is possible to modify the width of tracks and the size of vias without re-routing them using the Edit Tracks and Vias dialog. See the section below on bulk editing tools for details.

The length tuning tools can be used to add serpentine tuning shapes to tracks after routing. To tune the length of a track, first pick the appropriate length tuning tool. The single track tuning tool (icon or hotkey 7) will add serpentine shapes to bring the length of a single track up to the target value. The differential pair tuning tool (icon or hotkey 8) will do the same for a differential pair. The differential pair skew tuning tool (icon or hotkey 9) will add length to the shorter member of a differential pair in order to eliminate skew (phase difference) between the positive and negative sides of the pair. As with the Routing icons, the Tuning icons are found in both the Route menu dropdown from the top toolbar and the drawing toolbar on the right.

To select the target length for the length tuning tools, open the Length Tuning Settings dialog from the context menu or with the hotkey Ctrl+L after activating the length tuning tool:

This dialog can also be used to configure the size, shape, and spacing of the meander shapes.

After configuring the target length, click a track in the area that you wish to start placing meander shapes. Move the mouse cursor along the track, and meander shapes will be added. A status window will appear next to the cursor showing the current length of the track and the target length. Click again to finish placing the current meander. Multiple meanders can be placed on the same track if desired.

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.

The clearance and constraint resolution tools allow you to inspect which clearance and design constraint rules apply to selected items. These tools can help when designing PCBs with complex design rules where it is not always clear which rules apply to an object.

To inspect the clearance rules that apply between two objects, select both objects and choose Clearance Resolution from the Inspect menu. The Clearance Report dialog will show the clearance required between the objects on each copper layer, as well as the design rules that resulted in that clearance.

To inspect the design constraints that apply to an object, select it and choose Constraints Resolution from the Inspect menu. The Constraints Report dialog will show any constraints that apply to the object.

Dragging with the left mouse button will orbit the 3D view around the centroid of the board. Scrolling the mouse wheel will zoom the view in or out. Scrolling while holding Ctrl pans the view left and right, and scrolling while holding Shift pans up and down. Dragging with the middle mouse button also pans the view.

Different sized 3D grids can be set using the Preferences → 3D Grid menu. Bounding boxes for each component can be enabled with Preferences → Show Model Bounding Boxes.

When the PCB Editor and the 3D Viewer are both open, selecting a footprint in the PCB Editor will also highlight the component in the 3D Viewer. The highlight color is adjustable in Preferences → Preferences…​ → 3D Viewer → Realtime Renderer → Selection Color.

The current 3D view can be saved to an image with File → Export Current View as PNG…​ or Export Current View as JPG…​, depending on the desired image format. The current view can also be copied to the clipboard using the button, or Edit → Copy 3D Image.

The 3D Viewer has a raytracing rendering mode which displays the board using a more physically accurate rendering model than the default rendering mode. Raytracing is slower than the default rendering mode, but it can be used when the most visually attractive results are desired. Raytracing mode is enabled with the button, or with Preferences → Raytracing. The 3D grid and selection highlights are not shown in raytracing mode.

Colors and other rendering options, for both raytraced and non-raytraced modes, can be adjusted in Preferences → Preferences…​ → 3D Viewer.

Many viewing options are controlled with the top toolbar.

Include Layers: Check that every layer used on your board is enabled in the list. Disabled layers will not be plotted.

Output directory: Specify the location to save plotted files. If this is a relative path, it is created relative to the project directory.

Plot border and title block: If enabled, the drawing sheet border and title block will be plotted on each layer. This should usually be disabled when plotting Gerber files.

Plot footprint values: If enabled, the Value field of each footprint will be plotted on whatever layer it exists on (unless the field visibility is disabled for a specific footprint).

Plot reference designators: If enabled, the Reference Designator field of each footprint will be plotted on whatever layer it exists on (unless the field visibility is disabled for a specific footprint).

Force plotting of invisible values / refs: If enabled, all footprint values and reference designators will be plotted, even if the field visibility is disabled for some of these fields.

Plot Edge.Cuts on all layers: If enabled, the Edge.Cuts (board outline) layer will be added to all other layers. Check with your manufacturer to see what the correct value of this setting is for their manufacturing process.

Sketch pads on fabrication layers: If enabled, footprint pads on fabrication (F.Fab, B.Fab) layers will be drawn as unfilled outlines rather than filled shapes.

Do not tent vias: If enabled, vias will be left uncovered on the solder mask layers (F.Mask, B.Mask). If disabled, vias will be covered by solder mask (tented).

Drill marks: For plot formats other than Gerber, marks may be plotted at the location of all drilled holes. Drill marks may be created at the actual size (diameter) of the finished hole, or at a smaller size.

Scaling: For plot formats that support scaling other than 1:1, the plot scale may be set. The Auto scaling setting will scale the plot to fit the specified page size.

Plot mode: For some plot formats, filled shapes may be plotted as outlines only (sketch mode).

Use drill/place file origin: When enabled, the coordinate origin for plotted files will be the drill/place file origin set in the board editor. When disabled, the coordinate origin will be the absolute origin (top left corner of the worksheet).

Mirrored plot: For some plot formats, the output may be mirrored horizontally when this option is set.

Negative plot: For some plot formats, the output may be set to negative mode. In this mode, shapes will be drawn for the empty space inside the board outline, and empty space will be left where objects are present in the PCB.

Check zone fills before plotting: When enabled, zone fills will be checked (and refilled if outdated) before generating outputs. Plot outputs may be incorrect if this option is disabled!

Use Protel filename extensions: When enabled, the plotted Gerber files will be named with file extensions based on Protel (.GBL, .GTL, etc). When disabled, the files will have the .gbr extension.

Generate Gerber job file: When enabled, a Gerber job file (.gbrjob) will be generated along with any Gerber files. The Gerber job file is an extension to the Gerber format that includes information about the PCB stackup, materials, and finish. More information about Gerber job files is available at the Ucamco website.

Coordinate format: Configure how coordinates will be stored in the plotted Gerber files. Check with your manufacturer for their recommended setting for this option.

Use extended X2 format: When enabled, the plotted Gerber files will use the X2 format, which includes information about the netlist and other extended attributes. This format may not be compatible with older CAM software used by some manufacturers.

Include netlist attributes: When enabled, the plotted Gerber files will include netlist information that can be used for checking the design in CAM software. When X2 format mode is disabled, this information is included as comments in the Gerber files.

Disable aperture macros: When enabled, all shapes will be plotted as primitives rather than by using aperture macros. This setting should only be used for compatibility with old or buggy CAM software when requested by your manufacturer.

Scale factor: Controls how coordinates in the board file will be scaled to coordinates in the PostScript file. Using a different value for X and Y scale factors will result in a stretched / distorted output. These factors may be used to correct for scaling in the PostScript output device to achieve an exact-scale output.

Track width correction: A global factor that is added (or subtracted, if negative) from the size of tracks, vias, and pads when plotting a PostScript file. This factor may be used to correct for errors in the PostScript output device to achieve an exact-scale output.

Force A4 output: When enabled, the generated PostScript file will be A4 size even if the KiCad board file is a different size.

Units: Controls the units that will be used in the SVG file. Since the SVG format has no specified units system, you must export using the same units setting that you want to use for importing into other software.

Precision: Controls how many significant digits will be used to store coordinates.

Plot graphic items using their contours: Graphic shapes in DXF files have no width. This option controls how graphic shapes with a width (thickness) in a KiCad board are plotted to a DXF file. When this option is enabled, the outer contour of the shape will be plotted. When this option is disabled, the centerline of the shape will be plotted (and the shape’s thickness will not be visible in the resulting DXF file).

Use KiCad font to plot text: When enabled, text in the KiCad design will be plotted as graphic shapes using the KiCad font. When disabled, text will be plotted as DXF text objects, which will use a different font and will not appear in exactly the same position and size as shown in the KiCad board editor.

Export units: Controls the units that will be used in the DXF file. Since the DXF format has no specified units system, you must export using the same units setting that you want to use for importing into other software.

Default pen size: Controls the plotter pen size used to create graphics.

The IDF exporter exports an IDFv3 compliant board (.emn) and library (.emp) file for communicating mechanical dimensions to a mechanical CAD package. The exporter exports the board outline and cutouts, all pad and mounting through holes including slotted holes, and component outlines; this is the most basic set of mechanical data required for interaction with mechanical designers. All other entities described in the IDFv3 specification are currently not exported.

Once models have been specified for all desired components, the model of the board can be exported. In the PCB Editor, select File → Export → IDFv3…​.

Grid reference point: Choose where the exported model’s reference point should be. If the Adjust automatically option is selected, KiCad will set the reference point to the centroid of the PCB. Otherwise, the reference point is set relative to the display origin.

Output units: Choose whether the exported model’s units are millimeters or mils.

The outputs can be viewed directly in a mechanical CAD application or converted to VRML using the idf2vrml tool.

Hyperlynx: creates a file suitable for importing into Mentor Graphics (Siemens) HyperLynx simulation and analysis software.

The first time the PCB Editor (or any other KiCad tool that uses footprints) runs and the global footprint table file fp-lib-table is not found, KiCad will guide the user through setting up a new footprint library table. This process is described above.

Footprint libraries can only be used if they have been added to either the global or project-specific footprint library table.

Add a library either by clicking the button and selecting a library or clicking the button and typing the path to a library file. The selected library will be added to the currently opened library table (Global or Project Specific). Libraries can be removed by selecting desired library entries and clicking the button.

The and buttons move the selected library up and down in the library table. This does not affect the display order of libraries in the Footprint Library Browser, Footprint Editor, or Add Footprint tool.

Libraries can be made inactive by unchecking the Active checkbox in the first column. Inactive libraries are still in the library table but do not appear in any library browsers and are not loaded from disk, which can reduce loading times.

A range of libraries can be selected by clicking the first library in the range and then Shift-clicking the last library in the range.

Each library must have a unique nickname: duplicate library nicknames are not allowed in the same table. However, nicknames can be duplicated between the global and project library tables. Libraries in the project table take precedence over libraries with the same name in the global table.

Library nicknames do not have to be related to the library filename or path. The colon character (:) cannot be used in library nicknames or footprint names because it is used as a separator between nicknames and footprints.

Each library entry must have a valid path. Paths can be defined as absolute, relative, or by environment variable substitution.

The appropriate library format must be selected in order for the library to be properly read. KiCad supports reading KiCad (.pretty), KiCad legacy (.mod), Eagle (.lbr), and GEDA (folder with .fp files) footprint libraries.

There is an optional description field to add a description of the library entry. The option field is not used at this time so adding options will have no effect when loading libraries.

The footprint library tables support environment variable substitution, which allows you to define environment variables containing custom paths to where your libraries are stored. Environment variable substitution is supported by using the syntax ${ENV_VAR_NAME} in the footprint library path.

By default, KiCad defines several environment variables:

${KIPROJMOD} cannot be redefined, but the other environment variables can be redefined and new environment variables added in the Preferences → Configure Paths…​ dialog.

Using environment variables in the footprint library tables allows libraries to be relocated without breaking the footprint library tables, so long as the environment variables are updated when the library location changes.

${KIPROJMOD} allows libraries to be stored in the project folder without having to use an absolute path in the project library table. This makes it possible to relocate projects without breaking their project library tables.

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

Rendering Engine: Controls if Accelerated graphics or Fallback graphics are used.

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 lines 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.

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.

Flip board items L/R: Controls the direction board items will be flipped when moving them between the top and bottom layers. When checked, items are flipped Left-to-Right (about the Vertical axis); when unchecked, items are flipped Top-to-Bottom (about the Horizontal axis).

Step for rotate commands: Controls how far the selected object(s) will be rotated each time the Rotate command is used.

Allow free pads: Controls whether or not the pads of footprints can be unlocked and edited or moved separately from the footprint.

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 Shift to temporarily 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.

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 (45 degree mode)" will invoke the push-and-shove router to drag the track, respecting design rules and keeping other track segments attached. "Drag (free angle)" will move the nearest corner of the track segment, highlighting collisions with other objects but not moving them out of the way.

Limit actions to 45 degrees from start 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.

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

Refill zones after Zone Properties dialog: Controls whether or not zones are automatically refilled after editing the properties of any zone. This may be disabled on complicated designs or slower computers to improve responsiveness.

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. Neither of these built-in themes can 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.

The KiCad PCB editor supports plugins written in Python that can perform actions on the board being edited. These plugins can be installed using the built-in Plugin and Content Manager (see the KiCad chapter for details) or by placing the plugin files inside the user plugins directory. See the Scripting section below for details.

Each plugin that is detected will be shown in a row on this preferences page. Plugins may show a button on the top toolbar of the PCB editor. If the "Show button" control is unchecked for a plugin, it may still be accessed from the Tools > External Plugins menu.

The arrow controls at the bottom of the list allow changing the order that the plugins appear in the toolbar and menu. The folder button will launch a file explorer to the plugin folder, to make installing new plugins easier. The refresh button will scan the plugin folder for any new or removed plugins and update the list.

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.

The custom rules editor is located in the Board Setup dialog and provides a text editor for entering custom rules, a syntax checker that will test your custom rules and note any errors, and a syntax help dialog that contains a quick reference to the custom rules language and some example rules.

It is a good idea to use the Check rule syntax button after editing custom rules to make sure there are no syntax errors. Any errors in the custom rules will prevent the design rule checker from running.

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 a condition defining what objects to match, and a constraint defining the rule to be applied to the matched objects.

The language uses parentheses (( and )) to define clauses of related tokens and values. Parentheses must always be matched: for every ( there must be a matching ). Inside a clause, tokens and values are separated by whitespace. By convention, a single space is used, but any number of whitespace characters between tokens is acceptable. In places where text strings are valid, strings without any whitespace may be quoted with " or ', or unquoted. Strings that contain whitespace must always be quoted. Where nested quotes are required, a single level of nesting is possible by using " for the outer quote character and ' for the inner (or vice versa). Newlines are not required, but are typically used in examples for clarity.

In the syntax descriptions below, items in <angle brackets> represent tokens that must be present and items in [square brackets] represent tokens that are optional or only sometimes required.

The Custom Rules file must start with a version header defining the version of the rules language. As of KiCad 6.0, the version is 1. The syntax of the version header is (version <number>). So in KiCad 6.0 the header should read:

After the version header, you can enter any number of rules. Rules are evaluated in reverse order, meaning the last rule in the file is checked first. Once a matching rule is found for a given set objects being tested, no further rules will be checked. In practice, this means that more specific rules should be later in the file, so that they are evaluated before more general rules.

For example, if you create one rule that limits the minimum clearance between tracks in the net HV and tracks in any other net and a second rule that limits the minimum clearance for all objects inside a certain rule area, make sure the first rule appears later in the custom rules file than the second rule. Otherwise tracks in the HV net could have the wrong clearance if they fall inside the rule area.

Each rule must have a name and one or more constraint clause. The name can be any string and is used to refer to the rule in DRC reports. The constraint defines the behavior of the rule. Rules may also have a condition clause that determines which objects should have the rule applied and an optional layer clause, which specifies which board layers the rule applies to.

The custom rules file may also include comments to describe rules. Comments are denoted by any line that begins with the # character (not including whitespace).

The following properties can be tested in custom rule expressions:

Plugin scripts for the PCB editor can be installed automatically using the Plugin and Content Manager (PCM), or manually by copying the plugin to a folder. Each plugin should be in its own folder within the plugins folder. The location of the plugins folder is by default:

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.

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 button 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.

IDF component models are attached to footprints using the footprint’s 3D model properties. The IDF exporter uses different filetypes than the 3D viewer and other 3D model exporters, so adding 3D models for the IDF exporter does not conflict with 3D models added to a footprint for other purposes.

To add an IDF model to a footprint in the footprint or PCB editors, edit the footprint’s properties and click on the 3D Models tab.

Click the button and select the IDF (*.idf;*.IDF) filetype filter. Browse to the desired outline file.

Once the desired component outline file is selected, enter any necessary values for the offset and rotation. The offsets must be specified using the IDF board output units (mm or mils) and in the IDF coordinate system, which is a right-hand coordinate system with +Z pointing towards the viewer, +X to the viewer’s right, and +Y towards the upper edge of the screen. The rotation must be in degrees; positive rotation is a counter-clockwise rotation as described in the IDFv3 specification.

Multiple outlines may be combined with appropriate offsets to represent simple assemblies such as a DIP package in a socket.

The component outline file (*.idf) consists of a single .ELECTRICAL or .MECHANICAL section as described in the specification document. The section may be preceded by any number of comment lines; the comment lines are copied by the exporter into the library file and can be used to track metadata such as references to the documents used to determine the component’s outline and dimensions.

The component outline section contains fields which are strings, integers, or floating point numbers. A string is a combination of characters which may include spaces; if a string contains spaces then it must be quoted. Quotation marks must not appear within a string. Floating point numbers may be represented using decimal or exponential notations but decimal notation is preferred for human readability. The decimal point must be a dot and not a comma. The IDF file must consist only of 7-bit ASCII characters; use of 8-bit characters will result in undefined behavior.

An IDF file consists of SECTIONS which consist of RECORDS which consist of FIELDS. For the IDF outline files only one type of section may exist and must be one of .ELECTRICAL or .MECHANICAL. A record is a single line of text and may contain one or more fields. Fields are sequences of characters separated by one or more spaces which do not appear between quotation marks. All fields of a record must appear on a single line; records may not span lines.

The section heading (.ELECTRICAL or .MECHANICAL) is considered the first record (Record 1) of the section. Record 1 must be followed by Record 2 which has four fields:

Record 2 must be followed by a number of Record 3 entries which specify the outline of the component. Record 3 consists of four fields:

Only one closed loop is permitted and it is not possible to specify a cutout. The last point specified must be the same as the first point unless the outline is a circle.

Example IDF File 1:

Example IDF File 2:

When creating outlines, and especially when sharing the work with others, consistency in the design and naming of files helps people locate files quicker and place the components with minimal hassles.

A number of command-line tools are available to help generate IDF component outlines. The tools are: