KiCad Library Convention

Filenames, symbol names, footprint names, model names, 3D model names, and template names must contain only valid characters, as determined below:

This character set ensures that symbols will be compatible with all filesystems, and will not cause any issues due to character rendering.

Further, filenames and symbol names must not use the space character. This can cause issues with string escaping and is best avoided.

Libraries with more than 250 items can result in long library loading times. Additionally, such broad categorization of components means that it can be hard to locate a particular component in the libraries.

A library size limit of 250 items ensures that libraries are quick to load and components are easy to locate. If a given library exceeds 250 components, it should be split and further subcategorized according to component functionality.

Rather than grouping components (e.g. symbols, footprints) by their manufacturer, KiCad libraries are organized by component functionality. This grouping strategy has a number of key benefits:

Library organization should follow the general form as described below, with each element separated by the underscore (_) character:

Note: Some of the elements listed above may be omitted if not required.

For specific examples, refer to the guidelines for organizing symbol libraries and footprint libraries.

KiCad software is used by people who speak many different languages. The KiCad software provides translations for these languages, but the library files do not provide translations.

Library files should be written using English, excepting where specific component names are non-English (for non-English manufacturers).

Where potential differences in spelling and grammar exist, American English should be given preference.

In general, plural naming (e.g. for libraries) should be avoided, as pluralisation of some words is inconsistent. Non pluralized names should be used in preference:

Library files must always be commited to GitLab using Unix-style line endings. This means that lines are terminated using the LF (line feed) character, rather than the DOS style CR+LF line endings.

KiCad library files must be compatible across multiple operating systems, and users should be able to contribute without generating unnecessary noise in the files by constantly changing line endings.

When using the KiCad libraries on a Windows PC, the line endings in the library files may be automatically converted to CR+LF. This is fine, as long as any contributions made to the libraries observe the LF line ending requirements.

This issue is addressed by insisting that all KiCad libraries include a .gitattributes file. This file ensures that the line endings are automatically converted by Git.

An example of a simple .gitattributes file which ensures footprint files have correct line endings is as follows:

Note: The KiCad library repositories should already have the correct .gitattributes file in place to achieve this

Contributions of library assets must be created in the latest stable version of KiCad.

This is to avoid problems caused by changes in how assets are stored in different versions of KiCad. (Changes in how line ordering is determined, how strings are escaped, etc.) Another reason is to avoid including features not supported by the latest stable release.

KiCad has two workflows regarding what a symbol represents and when it is assigned a footprint. It can be done in the library in which case the symbol represents an exact part or using the "Assign Footprints" tool at the end of the design process.

Generic symbols

Generic symbols can be used with multiple footprints. They do not have a default footprint assigned. Generic symbols allow flexibility in the design workflow. For this workflow the symbol placed into the schematic is typically selected to fit the intended function instead of fitting a particular part. The footprint assignment happens later when the exact part number is selected. Using generic symbols allows a small number of library symbol elements to represent a very large number of possible component combinations.

An example of the use of generic symbols are the Resistor and Capacitor symbols available in the KiCad library. These symbols do not have an assigned default footprint, as there are many possible compatible footprints.

Fully specified symbols

Fully specified symbols define a matching footprint, and are named based on the MPN (manufacturer part number). Such symbols do not depend on the user to select the correct footprint later but can have alternative footprints defined using footprint filters such that the user can select an alternate footprint.

A fully specified symbol together with a footprint specialized to one component are called an atomic part. A library of only such parts is called an atomic library. Confusingly, some users refer to a fully specified symbol as an atomic symbol.

Where to use which type

The official library requires fully specified symbols except for a small number of libraries that contain only generic symbols. These generic libraries are:

Symbol libraries are individual .lib files, which have a corresponding .dcm file. Both files are required to fully describe the symbols contained in the library. Apart from the file extension, both files must have the same name (case sensitive).

Symbol library names must be defined based on the priority list below, with each element separated by the underscore (_) character:

Note: Some of the elements listed above may be omitted if not required.

Example symbol library names:

Manufacturer Part Numbers (MPN) often include variations that are non-functional.

Examples of parameters considered non-functional:

To capture every possible combination of part variation would require a large number of symbol aliases and is to be avoided.

Where an MPN has options for such non-functional variations, these portions of the MPN should be replaced with a wildcard character (x). If these non-functional parts of the MPN are at the end of the symbol name then the wildcard should be omitted.

Many electronic components are provided in multiple packages. These may or may not be pin compatible.

KiCad is not able to assign different footprints for aliases. Fully specified symbols therefore require a separate symbol for every package. Footprints in KiCad have a 1:1 relationship with their 3D model. This means multiple footprints are required where the 3D model has functional differences even if the footprints are identical (for example when 3D model height differs).

e.g. LTC4357

This part comes in two distinct packages each requiring a separate footprint. Hence a symbol for each variant must be drawn.

For naming of the symbols refer to General symbol naming guidelines

Where possible, the symbols should be drawn such that they can be swapped in the schematic with minimal disruption to wire connections.

As a further example we shall consider the comparator MCP6566 which is available in three SOT-23-5 versions, each with a different pinout.

In this case, a separate symbol must again be drawn for each version, and named according to the convention called out in the datasheet.

For symmetrical symbols, the symbol must be centered around the origin (0, 0) in the symbol editor.

Exception:

For non-symmetrical symbols, or symbols where this requirement would move pins off the 100mil grid, then the symbol should be placed as close to the origin as possible while observing the pin grid alignment requirements.

Fill background

Do not fill

For black box symbols with complex functionality (e.g. special function ICs), a simplified diagram of the symbol functionality may be drawn on the symbol. This may be used to provide functional clarity in a schematic.

Connection points for symbol pins must be placed outside the symbol body and must not require a connecting wire to cross the symbol.

Example of incorrect symbol:

Example of correct symbols:

Examples:

For IC components with exposed pads, the number of the exposed pad should start one greater than the pin-count of the footprint.

For a SOIC-8 package with a single exposed pad, the exposed pad will be assigned the number 9

Shielded components use "SH" as the pin number for connecting the shield. For a pin to qualify as the shield pin it must be connected to a metal enclosure. For connectors it must connect to the shield of the cable.

Parts that include mechanical mounting pads without electrical use, get the pin number "MP". Non plated through holes do not get any pad number assigned. (They do not get a pin in the symbol.) An example for such a pure mechanical mounting pad would be the pads for the two metal leads on the side of Molex picoblade smd connectors.

This approach should not be taken for single-unit symbols. Power pins in this case must be drawn on the same symbol as the logic pins.

Where possible, pins should be grouped by similar function, rather than by their physical location on the associated footprint. This provides cleaner schematic routing and symbols are easier to understand in the schematic.

Many symbols have corresponding footprints where multiple physical pins are connected to a single logical net. It is desirable that in such cases the user only has to connect a single pin in the schematic, and it will automatically route to all the physical pins on the PCB. (This is not only done to reduce clutter in the schematic drawing. The main reason is to move some responsibility for correct connections from the circuit designer over to the library.)

KiCad currently has no native method for designating that a particular symbol pin maps to multiple footprint pins. The following guide serves as a workaround for designing such symbols.

In the schematic view, pins that share the same position are considered to be connected by the KiCad routing algorithm. Thus, pins can only be placed in the same location under a very specific set of circumstances:

Special Case: Pins of electrical type [Output, Power Output, Power Input] are special cases.

Pin Electrical type should be set to match the appropriate pin function

Often a component has pins that are not physically connected. Even these pins should be included in the symbol. Refer to the requirements for hidden pins.

However in some cases unconnected pins may be omitted from the schematic symbol.

Hidden symbol pins are generally not allowed for schematic symbols. Any connection point must be visible, otherwise unexpected net connections can occur.

Exceptions

Rather than selecting the active low graphical pin style, active low pins should be designated using a bar above the pin name.

This provides a cleaner look for the schematic.

To place a line above the pin text, prefix the name with the tilde (~) character. In case of a pin name where only part of it is active low, and hence, not all of it needs a bar above, two tilde characters must be used as delimitation, e.g. ~SPD_LED~/GPIO2.

If the pin name given by the manufacturer includes an active low prefix or suffix, it should be removed when adding the bar above it to avoid negating it twice. For example for nRESET, use ~RESET.

Footprint filters are used to help match appropriate footprints to a given symbol. This is important even for fully specified symbols (symbols with only one matching footprint), as there still may be multiple compatible footprints with different variants or options (e.g. _HandSoldering, _Heatsink, _ThermalVias).

Footprint filters use wildcard pattern matching, and allow the following wildcards:

The library name can be used as a filter criterium. The delimiter between library and footprint filtering is :

Filter conventions:

Footprint filters can be set in the Footprint Filter tab in the Symbol Properties window.

The symbol Reference Designator must be filled out appropriately for the particular type of symbol.

The table below provides a list of appropriate RefDes values. If you do not find an appropriate component entry, consult with the KiCad library team.

Additional documentation is provided via two other fields:

Aliases define their own values for the datasheet link, description and keyword entries.

[1]: KiCad 5.x and earlier have two places to store the datasheet link. It can be in the .lib file once per symbol or in the .dcm file allowing different datasheets per alias. Having different datasheets for aliases only works if the .lib entry is left empty. The datasheet entry in the main symbol metadata view is linked to the dcm entry since version 5.1.x.

Power flag symbols are special symbols in KiCad, used to designate global nets. These symbols use a special RefDes value to indicate that they must be considered as global power flags

The example image below demonstrates the requirements as listed above:

Graphical symbols are used only to annotate schematics and do not correspond to a footprint on the PCB.

Example:

Footprints are grouped into libraries (directories with .pretty extension) based on their primary function. As an extension of this, footprint libraries should be named based on this same functionality.

Library names must be defined based on the priority list below, with each element separated by the underscore (_) character:

Note: Some of the elements listed above may be omitted if not required.

Example footprint library names:

Categorizing connectors by function can prove difficult as many connectors can be used in a wide variety of applications.

Therefore, categorization of connector footprints is given special consideration as detailed below:

Each footprint is a .kicad_mod file (stored within a .pretty directory). The naming convention for a given footprint depends largely on the type of footprint, however a general guide is presented below:

Not all of the fields defined above are strictly required for a particular footprint. Additional fields may also be added as needed.

A footprint name has to convey a lot of information to clearly specify the purpose and parameters of the footprint. Some fields in footprint names are common to many footprints and can be shortened using special abbreviations.

Not all footprints will require the use of these abbreviations - they are provided as a method of standardising the manner in which footprint parameters are called out when encountered.

In many cases, the major dimensions (x/y/z) of a footprint may be specified without a prefix, as the body dimensions are assumed to have the greatest priority in the footprint name. Therefore, the "3.2x5.7mm" part of the example name below requires no 'B' prefix, and is not required to be written as "B3.2x5.7mm".

e.g. SOIC-8_3.2x5.7mm_P1.27mm

In cases where potential conflicts exist, however, the body dimensions must be explicitly named with the prefix B.

Refer to the table below for accepted prefix abbreviations.

Examples:

If the parameter is not found in the table above, the name of the parameter should be entered in full.

Following is a list of examples of (non-abbreviated) parameter names used in footprint naming

If a manufacturer footprint deviates from the "standard" footprints available, then this should be added to the library and designated as manufacturer-specific.

In such cases, the KLC requirements can be superseded by the datasheet requirements, at the discretion of the KiCad library team.

Generally, a footprint should include a field of the format <pkg>-<pincount>, e.g.

In the majority of cases, the pin quantity is self explanatory and is sufficient to describe the number of pins on the symbol.

However there may be cases where this numbering is insufficient. Where the number of footprint pins does not match the number of package pins, exceptions must be made.

Exception: Omitted pins, missing pin numbers are skipped

Example: LTC3638

The LTC3638 comes in an MSOP-16 package which has four missing pins, for increased voltage isolation.

In this case, the numbers for the missing pins are skipped and the normal pin numbers are assigned to the remaining pins.

To indicate this, the footprint should be named as follows:

PKG-<xx>-<yy> where:

In the LTC3638 example above, this would result in:

MSOP-12-16

The footprint pads should be numbered like so:

Footprint naming is sufficiently complex that a general rule is not enough to fully define a naming scheme that fits the wide range of footprints.

In addition to the general footprint naming guidelines defined in KLC 2.1, a set of footprint naming guidelines for specific footprint types is provided in KLC F3.x.

The following footprint naming conventions should be used as examples for naming SMD chip package footprints.

If you do not find an appropriate convention that matches a particular footprint type, either contact the KiCad library team or try to match a convention set by existing library components.

In the entries below, variable fields are denoted as follows:

- Fixed fields
- Mandatory fields
- Optional fields

• Prefix - Device type
• Imperial size - Imperial case size (Optional)
• Metric size - Metric case size (Optional)
• Modifiers - Modifiers to footprint if non standard (Optional)
• Options - Extra footprint options (Optional)

Example:

Notes:

The prefix is determined by the default reference designator of the device, e.g.

Case size codes:

The following footprint naming conventions should be used as examples for naming resistor footprints.

If you do not find an appropriate convention that matches a particular footprint type, either contact the KiCad library team or try to match a convention set by existing library components.

In the entries below, variable fields are denoted as follows:

- Fixed fields
- Mandatory fields
- Optional fields

The following footprint naming conventions should be used as examples for naming capacitor footprints.

If you do not find an appropriate convention that matches a particular footprint type, either contact the KiCad library team or try to match a convention set by existing library components.

In the entries below, variable fields are denoted as follows:

- Fixed fields
- Mandatory fields
- Optional fields

The following footprint naming conventions should be used as examples for naming SMD IC package footprints.

If you do not find an appropriate convention that matches a particular footprint type, either contact the KiCad library team or try to match a convention set by existing library components.

In the entries below, variable fields are denoted as follows:

- Fixed fields
- Mandatory fields
- Optional fields

The following footprint naming conventions should be used as examples for naming THT IC package footprints.

If you do not find an appropriate convention that matches a particular footprint type, either contact the KiCad library team or try to match a convention set by existing library components.

In the entries below, variable fields are denoted as follows:

- Fixed fields
- Mandatory fields
- Optional fields

The following footprint naming conventions should be used as examples for naming connector footprints.

If you do not find an appropriate convention that matches a particular footprint type, either contact the KiCad library team or try to match a convention set by existing library components.

In the entries below, variable fields are denoted as follows:

- Fixed fields
- Mandatory fields
- Optional fields

The following footprint naming conventions should be used as examples for naming fuse and fuse holder footprints.

If you do not find an appropriate convention that matches a particular footprint type, either contact the KiCad library team or try to match a convention set by existing library components.

In the entries below, variable fields are denoted as follows:

- Fixed fields
- Mandatory fields
- Optional fields

Where conflict exists between datasheet recommendations and KLC requirements, then (in the general case) the datasheet should take priority.

It is important when designing footprints that they adhere to requirements for soldering and assembly - often these requirements have very small tolerance for variation.

If the KLC is at odds with the datasheet, follow the datasheet, and note this difference to the KiCad library team when submitting your contribution.

Footprints should be oriented such that Pin 1 is located in the upper left corner (IPC-7351).

Exceptions

Where footprints cannot be oriented with pin 1 in the top-left quadrant, pin 1 should be aligned to the top

Two terminal footprints should be aligned with pin 1 on the left side

Footprints that contain multiple pads or conductive elements that are physically connected require special attention:

Manufacturer datasheets may specify that thermal vias should be added to the thermal pad under a device package, to assist in moving heat away from the device.

In such cases the datasheet will usually specify the quantity, size and position of these vias.

In addition to manufacturer requirements, a number of extra conventions should be followed when creating thermal vias.

KiCad does not yet have a method for drawing keepout areas inside footprint files. Until this feature is implemented, footprint keepout must should be indicated using the following procedure:

Example:

Pad clearance values are determined using a priority system, which checks the following locations for clearance values, in descending order of priority. If a particular setting reads as zero (0) then it is ignored, and the next location is checked.

Unless there is a specific reason for setting explicit values for local clearance values for pads or pins, they should be left at zero (0).

Exceptions:

If the component datasheet calls for specific clearance values for a particular pad (or the entire footprint) then these values should be used as appropriate.

The silkscreen is printed to the external surface of a PCB to aid in component identification and orientation. Typically this layer contains the component RefDes to locate components on the board after assembly.

KiCad refers to the silkscreen layers as:

The following elements must be provided on the silkscreen.

Examples of silk for non polarized components

Examples of silk for polarized components

The fabrication layers are used to display the simplified mechanical outline of components on the PCB.

KiCad refers to the fabrication layers as:

The following elements must be provided on the fabrication layer(s)

The component courtyard is defined as the smallest rectangular area that provides a minimum electrical and mechanical clearance around the combined component body and land pattern boundaries. It is allowed to create a contoured courtyard area using a polygon instead of a simple rectangle. (IPC-7351C)

The courtyard should include any extra required clearance for mating connectors (for example).

KiCad refers to the courtyard layers as:

A fully enclosed Component courtyard must be drawn on the F.CrtYd layer, with the following parameters:

Courtyard clearance should adhere to the following requirements:

Example for courtyard clearance when applied to the contoured courtyard outline of a QFP-64 package. (Shown are courtyard, fab-outline and copper pads.)

Footprints should not have overlapping or duplicate graphic elements. This includes lines, arcs and circles. Touching endpoints or intersections are not considered as overlapping.

The Footprint placement type must be set to Surface mount for SMD footprints. This is to ensure that these footprints are included in the Footprint position (.pos) file output.

To set the footprint placement type, open the Footprint properties window and select Surface Mount as indicated.

In KiCad 4.x, Placement type is called Attributes and Surface mount is called Normal+Insert.

The footprint anchor (also called component origin) is used by automated Pick and Place (PNP) machines for locating and placing SMD components on a PCB.

For most standard components, the anchor should generally be located on the centroid of the component body.

In the KiCad footprint editor, the footprint anchor is always located at the origin (0, 0). To move the footprint relative to the anchor (origin), press the Place footprint reference anchor button (refer to image below).

Exceptions:

Some footprints (especially those which are non-symmetrical) require special consideration and the anchor may not necessarily be placed on the component centroid.

Generally speaking, the correct location of the footprint anchor can be found in the component datasheet. The image below shows an example for a Molex Pico-Lock connector.

Surface mount pads have specific requirements for PCB design.

Requirements for solderpaste

Many components (IC packages in particular) have specific design requirements for solderpaste (stencil) design. These requirements are often found in the footprint datasheet or an associated technical document.

Most often, custom stencil openings are required for the exposed pads on large IC packages to reduce the amount of solderpaste that is applied during stencil application.

The image below shows an example stencil design found in a footprint datasheet. The superimposed blue square represents the shape of the exposed copper pad. The green squares are the required openings in the stencil.

Custom stencil openings are accommodated as follows:

Result: (note: this footprint does not correspond to the example shown above)

Size of exposed pads

The following rules apply for finding the correct pad size for parts including an exposed pad.

Clearance requirement between exposed pads and normal pads

The footprint placement type must be set to Through Hole for THT footprints. This ensures that these footprints are not included in the Pick and Place (PNP) location files.

This can be selected in the Footprint Properties window

In KiCad 4.x, Placement type is called Attributes and Through hole is called Normal.

For through hole components the footprint anchor should be placed at the location of pin 1.

Through hole components should set the shape of Pin 1 to Rectangular or Rounded Rectangle, and all other pads to either Circular or Oval. This aids in orienting the component during placement and also for locating Pin 1 for circuit troubleshooting. For rounded rectangle pads the corner size should be 25% with a maximum radius of 0.25mm.

Pad shape can be adjusted in the Pad Properties dialog:

Exception:

Non polarized parts (such as THT resistors) should not set the shape of Pin 1 to Rectangular. For these (non polarized) footprints, all pad shapes should be consistent.

Through hole pads must have soldermask pulled back to allow soldering. However they must not have solderpaste openings as they do not receive solder paste during stencil screening.

For drilled through-holes, the minimum annular ring width must be at least 0.15mm (IPC-2221).

The annular ring is the copper pad which remains after the hole has been drilled.

For drilled through-holes, minimum drilled hole diameter is the maximum lead diameter plus 0.2mm (IPC-2222 class 2)

Maximum lead diameter is obtained from the device datasheet.

The sizes for oval holes must be chosen such that there is 0.2mm clearance between the maximum lead size and the hole in all directions. Oval holes are only allowed if the lead length to width ratio is greater than 2. (Lead cross section is at least twice as long as wide)

Maximum lead dimensions are obtained from the device datasheet.

Some PCB manufacturers are not able to produce milled slots. It is allowed to add an alternative footprint using only circular holes. These need to follow the same drill size increase as all other holes. The equivalent lead diameter should be rounded up to the next 0.01mm increment.

The footprint name of such an alternative is marked with the suffix _CircularHoles.

Virtual components are those which have a footprint on the PCB (and may additionally have a schematic symbol) but do not have an associated physical component which needs to be loaded onto the board during assembly.

Examples of virtual components include:

Virtual components must be indicated by setting the Placement type to Virtual in the Footprint Properties dialog.

Footprint properties should be left as default, unless there is a reason to do so as specified by the footprint datasheet (for example).

Exceptions:

The Local Clearance Values parameters are generally set to 0, indicating that the global clearance values will be used to determine pad clearances.

If all the pads on the particular footprint require a specific clearance value (for e.g. as described by the datasheet) then these values can be used here to override pad-specific settings for the entire footprint.

The goal of the KiCad 3d model library is to provide a free open library of 3d models. This requires certain restrictions regarding contributions with respect to their legal status.

This rule was withdrawn.

The KiCad library maintains a repository for 3D source files at https://gitlab.com/kicad/libraries/kicad-packages3D-source.

The source files used to generate 3D model data must be submitted to this repository when a user contributes 3D model data.

Any 3D model contribution to the KiCad library must be made in both step and wrl format.

WRL

STEP

The 3D models must be aligned and scaled appropriately to match the associated footprint.

Alignment

The 3D model must be aligned such that it does not require an additional alignment offset in the footprint options. When associating a 3D model with a footprint, the offset parameter must read (0, 0, 0)

Scaling

Rotation

The model must be rotated such that no additional rotation is required within KiCad to align the 3D model with the footprint.

The goal of the KiCad 3d model library is to provide a free open library of 3d models. The use of open source design tools is preferred for this very reason.

Freecad is chosen as the preferred tool to be used. Especially in combination with the kicad-stepup extension.

Good alternatives are open scripting options like OpenSCAD or CadQuery. For the latter consider contributing to https://gitlab.com/kicad/libraries/kicad-packages3D-generator

Files created in closed source tools are permitted. If a certain model is available designed in both an open and closed tool then the one from the open tool is preferred and will replace the other one.