:experimental:

[[managing-symbol-libraries]]
== Managing Symbol Libraries

Symbol libraries hold collections of symbols used when creating schematics. Each symbol
in a schematic is uniquely identified by a full name that is composed of a library nickname
and a symbol name. An example is `Audio:AD1853`.

=== Symbol Library Table

KiCad uses a table of symbol libraries to map symbol libraries to a library
nickname. Kicad uses a global symbol library table as well as a table specific
to each project. To edit either symbol library table, use **Preferences** ->
**Manage Symbol Libraries...**.

image::images/en/options_symbol_lib.png[scaledwidth="80%",alt="sym lib table dlg"]

The global symbol library table contains the list of libraries that are
always available regardless of the currently loaded project. The table is
saved in the file `sym-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 symbol library table contains the list of libraries that
are available specifically for the currently loaded project. If there are any
project-specific symbol libraries, the table is saved in the file
`sym-lib-table` in the project folder.

==== Initial Configuration

The first time the KiCad Schematic Editor is run and the global symbol table
file `sym-lib-table` is not found in the KiCad configuration folder, KiCad will
guide the user through setting up a new symbol library table. This process is
described <<initial-configuration,above>>.

==== Managing Table Entries

Symbol libraries can only be used if they have been added to either the
global or project-specific symbol 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 Symbol Library Browser, Symbol Editor, or Add Symbol 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 symbol names
because it is used as a separator between nicknames and symbols.

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. "KiCad" format is used for KiCad version 6 libraries
(`.kicad_sym` files), while "Legacy" format is used for libraries from
older versions of KiCad (`.lib` files). Legacy libraries are read-only,
but can be migrated to KiCad format libraries using the **Migrate
Libraries** button (see section <<migrating-libraries,Migrating Legacy 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.

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

The symbol 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 symbol library path.

By default, KiCad defines several environment variables:

* `${KIPROJMOD}` points to the current project directory and cannot be modified.
* `${KICAD6_FOOTPRINT_DIR}` points to the default location of KiCad's standard
  footprint libraries.
* `${KICAD6_SYMBOL_DIR}` points to the default location of KiCad's standard
  symbol libraries.
* `${KICAD6_3DMODEL_DIR}` points to the default location of KiCad's standard 3D
  model libraries.
* `${KICAD6_TEMPLATE_DIR}` points to the default location of KiCad's standard
  template library.

`${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 symbol library tables allows libraries to
be relocated without breaking the symbol 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.
One of the most powerful features of the symbol library table is
environment variable substitution. This allows for definition of
custom paths to where symbol libraries are stored in environment
variables. Environment variable substitution is supported by using
the syntax `${ENV_VAR_NAME}` in the library path.

==== Usage Patterns

Symbol libraries can be defined either globally or specifically to the currently
loaded project. Symbol libraries defined in the user's global table are always
available and are stored in the `sym-lib-table` file in the user's KiCad
configuration folder. The project-specific symbol library table is active only
for the currently open project file.

There are advantages and disadvantages to each method. Defining all
libraries in the global table means they will always be available when
needed. The disadvantage of this is that load time will increase.

Defining all symbol libraries on a project specific basis means that
you only have the libraries required for the project which decreases
symbol library load times. The disadvantage is that you always have
to remember to add each symbol library that you need for every
project.

One usage pattern would be to define commonly used libraries globally
and the libraries only required for the project in the project specific
library table. There is no restriction on how to define libraries.

[[migrating-libraries]]
==== Migrating Legacy Libraries

Legacy libraries (`.lib` files) are read-only, but they can be migrated
to KiCad version 6 libraries (`.kicad_sym`). KiCad version 6 libraries
cannot be viewed or edited by KiCad versions older than 6.0.0.

Legacy libraries can be converted to KiCad 6 libraries by selecting them in the
symbol 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 Symbol
Editor and saving them as a new library.

==== Legacy Project Remapping

When loading a schematic created prior to the symbol library table
implementation, KiCad will attempt to remap the symbol library
links in the schematic to the appropriate library table symbols.
The success of this process is dependent on several factors:

- the original libraries used in the schematic are still available
  and unchanged from when the symbol was added to the schematic.

- all rescue operations were performed when detected to create a
  rescue library or keep the existing rescue library up to date.

- the integrity of the project symbol cache library has not been
  corrupted.

[WARNING]
====
The remapping will make a back up of all the files that are changed
during remapping in the rescue-backup folder in the project folder.
Always make a back up of your project before remapping just in case
something goes wrong.
====

[WARNING]
====
The rescue operation is performed even if it has been disabled to
ensure the correct symbols are available for remapping.  Do not
cancel this operation or the remapping will fail to correctly
remap schematics symbols.  Any broken symbol links will have to
be fixed manually.
====

[NOTE]
====
If the original libraries have been removed and the rescue was not
performed, the cache library can be used as a recovery library as a
last resort. Copy the cache library to a new file name and add the
new library file to the top of the library list using a version of
KiCad prior to the symbol library table implementation.
====
