:experimental:

== Footprints and footprint libraries

KiCad organizes footprints into footprint libraries, which hold collections of
footprints. Each footprint in a board is uniquely identified by a full name that
is composed of a library nickname and a footprint name. For example, the
identifier `Capacitor_SMD:C_0603_1608Metric` refers to the `C_0603_1608Metric`
footprint in the `Capacitor_SMD` library.

[[managing-footprint-libraries]]
=== Managing footprint libraries

KiCad uses a table of footprint libraries to map footprint libraries of any
supported library type to a library nickname. KiCad uses a global footprint
library table as well as a table specific to each project. To edit either
footprint library table, use **Preferences** -> **Manage Footprint
Libraries...**.

image::images/en/fp_lib_table.png[scaledwidth="80%",alt="footprint library table dialog"]

The global footprint library table contains the list of libraries that are
always available regardless of the currently loaded project. The table is
saved in the file `fp-lib-table` in the KiCad configuration folder.
xref:../kicad/kicad.adoc#config-file-location[The location of this folder]
depends on the operating system being used.

The project specific footprint library table contains the list of libraries that
are available specifically for the currently loaded project. If there are any
project-specific footprint libraries, the table is saved in the file
`fp-lib-table` in the project folder.

KiCad's footprint library management system allows directly using many types
of footprint libraries, including formats that are native to other non-KiCad EDA
tools:

* KiCad `.pretty` footprint libraries
  (folders with `.pretty` extension, containing `.kicad_mod` files)
* KiCad Legacy footprint libraries (`.mod` files)
* Altium Designer (`.PcbLib` or `.IntLib` files)
* CADSTAR PCB Archive (`.cpa` files)
* Eagle footprint libraries (`.lbr` files)
* EasyEDA / JLCEDA Standard Edition (`.json` or `.zip` files)
* EasyEDA / JLCEDA Professional Edition (`.elibz`, `.epro`, or `.zip` files)
* GEDA libraries  (folders containing `.fp` files)

Non-KiCad footprint libraries, including KiCad Legacy footprint libraries, can
be migrated to KiCad `.pretty` format using the **Migrate Libraries** button
(see the <<migrating-footprint-libraries,migrating libraries>> section).

NOTE: KiCad only supports writing to KiCad's native `.pretty` format footprint
libraries (and the `.kicad_mod` footprint files within them). All other
footprint library formats are read-only. To modify a non-KiCad format footprint
library, you must first convert it to KiCad format.

==== Initial Configuration

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 <<initial-configuration,above>>.

==== Managing Table Entries

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
image:images/icons/small_folder_16.png[Folder icon] button and selecting a
library or clicking the image:images/icons/small_plus_16.png[Plus icon] 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
image:images/icons/small_trash_16.png[Delete icon] button.

The image:images/icons/small_up_16.png[Up icon] and
image:images/icons/small_down_16.png[Down icon] 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 kbd:[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,environment variable substitution>>.

The appropriate library format must be selected in order for the library to be
properly read. The supported formats are listed above. Only KiCad format
libraries (`.pretty` folders containing `.kicad_mod` files) can be saved. Other
footprint library formats are read-only and must be converted to KiCad format
before you can modify them.

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.

[[environment-variable-substitution]]
==== Environment Variable Substitution

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 which are described in
the xref:../kicad/kicad.adoc#kicad-environment-variables[project manager documentation].
Environment variables can be configured 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.

`${KIPRJMOD}` is a special environment variable that always expands to the
absolute path of the current project directory. `${KIPRJMOD}` 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.

==== Using the GitHub Plugin

NOTE: KiCad removed support for the GitHub library plugin in version 6.0.

[[migrating-footprint-libraries]]
==== Migrating footprint libraries to KiCad format

Non-KiCad format libraries, including legacy libraries (`.mod` files), are
read-only. They need to be converted to KiCad format (`.kicad_mod` files in a
`.pretty` folder) before you can save changes to them.

NOTE: As with most KiCad files, newer versions of KiCad can open older-format
      library files, but older versions of KiCad cannot read files once they
      have been saved by a newer version of KiCad.

Libraries in other formats can be converted to KiCad libraries by selecting them
in the footprint library table and clicking the **Migrate Libraries** button.
Multiple libraries can be selected and migrated at once by kbd:[Ctrl]-clicking
or kbd:[shift]-clicking.

Libraries can also be converted one at a time by opening them in the Footprint
Editor and saving them as a new library.

[[creating-and-editing-footprints]]
=== Creating and editing footprints

NOTE: This section of the KiCad documentation has not yet been written.  We
      appreciate your patience as our small team of volunteer documentation
      writers work to update and expand the documentation.

[[custom-pad-shapes]]
==== Custom pad shapes

[[footprint-attributes]]
==== Footprint attributes

NOTE: Mention net ties here

[[footprint-wizards]]
==== Footprint wizards

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