Library management in KiCad version 5

Disclaimer: screenshots taken in nightly from between version 5.0 and 5.1. Version 5.0.x looks slightly different. Version 5.1.x will look like the screenshots show.

This is a detailed lecture. If you want to know how to simply add some assets you downloaded to KiCad then you can read the shorter tutorial How to get a downloaded symbol, footprint or full library into KiCad version 5?

Summary

KiCad does not automatically detect libraries! There is no special library location (you might still care about good file organization). The path (variable) setup found in the preferences menu is for making your setup portable not to load a full directory of libraries.

Every library that should be available must be added to so called library tables which are managed with library managers. These are found in the preferences menu of all KiCad subprogramms (preference -> Manage symbol/footprint libraries.)

KiCad splits footprint and symbol libraries. Even if symbols are setup to point directly to footprints you still need to add the footprint libraries to the library table.
There are two library tables for every asset type with differing skope. One is global and the other local to the current project. (Project local entries have higher priority in case there is a nickname conflict.)

Use the “add existing library” button of the library manager to add libraries using a file browser like tool that allows selecting multiple libs via shift or crtl plus left click.
Alternatively use the add library entry of the file menu within the footprint and symbol editors. This tool does not allow to add multiple libraries at once. Use it to add a sinlge downloaded library to KiCad.

For more details continue reading.

Introduction

Official KiCad documentation (Disclaimer: parts of the official docu especially on the footprint side are out of date at the time of writing. Meaning some menus look a bit different. But you should still be able to find the correct tools from the information given as long as you accept slight changes in the wording used to reference them from the menu.):

The KiCad library system separates symbols and footprints in their own libraries. This does add a lot of flexibility but comes with its own set of challenges.

Symbols abstract the function of a component and communicate the interface of it to both KiCad and the person reading the schematic. Footprints define the physical interface between the pcb and the component (The land pattern) and also include documentation information (outline, polarization mark, reference, …)
Here a more in depth explanation about the differences between symbols and footprints.

File types

Symbol libraries

Every symbol library consists of two files. The .lib file defines most of the symbol (graphical elements like pins and lines, symbol fields like the default footprint, …) The .dcm file holds the information that can be specialized for every symbol alias. (Description, keywords and datasheet link)

Most kicad internal dialogs will only show the .lib file. KiCad knows that there also is a .dcm file with the same file name.

Footprint libraries

The current footprint file format has one .kicad_mod file per footprint placed in a folder with .pretty suffix representing the library.
In some rare instances you might also find the pre version 4 file format. Back then a single .mod file represented a full library. (similar to how symbol libs are handled right now.) KiCad can still include them in the library setup in the same way as a its modern files.

KiCad can also directly use eagle xml libraries to extract footprints. (To do that add the library file to the footprint library table.)

3d model libraries

KiCad supports wrl and step files. It is customary that these files are organized in .3dshapes directories. (Kind of like libraries but KiCad does not really manage them. More on that later.)

The library nickname (library identifier)

The nickname is used as an abstraction between KiCad and the filesystem. Every symbol (or footprint) is uniquely identified by the combination of library nickname and symbol (or footprint) name. The colon (":") character is used as a delimiter between them.

Library tables

Libraries are not available from within KiCad by simply placing them in some specific file system location. (One major difference to how eagle handles libraries.) Every library must be explicitly added to so called library tables. (fp-lib-table for footprints, sym-lib-table for symbols) These library tables are managed using library managers. See below for an in depth explanation of these tools.

There is a global and local version of both of these tables. Every library added to the global table is visible for all projects whereas adding a library to the local table makes it only visible from the current project.
The local table entries are used if a library with the same nickname is in both the global and local library table.

“Managing” 3d models

3d models are not managed in any way. Footprints directly point to a 3d model file. It is therefore recommended to use path variables for the 3d path settings of footprints.
This means care must be taken when placing models on the file system. It is suggested to place all your models in subdirectories of a common folder. That common folder is where your personal 3d model path variable might point to.

More details about adding 3d models
A suggestion for a file system organization can be found further down. (Including a suggestion for which environment variables to use and where to point them.)

Where should global libraries live within the file system.

KiCad does not really care where you place your library files as long as you point to them appropriately. The only restriction i would suggest you hold yourself to is that you do not place personal libs into the KiCad system path directory. Furthermore do not add personal symbols, footprints or 3d model libraries into one of the KiCad supplied libraries. (The next update of KiCad would delete your work if it is within the system directory.)

I would suggest that you put any personal library into some central location within your personal user home directory. (A KiCad-library subdirectory within your documents folder for example)

Setup a path variable to either your main library directory or your 3d model library to allow your footprints to be portable. (As mentioned in the 3d model section above.) I would suggest for a single path variable to your main library folder. (Allows your full setup to be portable instead of just having 3d models portable.) Path variables are managed in the KiCad main window -> preferences -> configure paths.

Also remember this is just a suggestion. If you do not like this suggested setup then you can use a different one.

Personalized setup for the official library

KiCad does come with official libraries that are by default installed (if you choose to do so) somewhere in a write protected area. There might however be reasons to deviate from this.

One reason would be if you want to have more control over which version of the official library is used in your setup. In that case placing your version of the official lib into your user directory makes a lot of sense.

You can choose to download a specific version of the lib directly from github or clone the repo with git allowing you to easily change between versions and download new ones. (more details about that further down.) The later option can save you data volume as well as git only downloads what changed. (A local git clone makes contributing to the library easier as well.)

To get this non standard location of the official lib to work you either need to point the path variables to these new locations (and use the default library tables) or use the library manager as explained further down to remove the old libs and add the new ones. Remember that you will need to set the 3d path variable (KISYS3DMOD) in any case.

My suggestion would be to use the default library table and pointing all 3 path variables to the new library location (as shown in the picture.) This will allow you to keep the official library table including the description of libraries while still being able to have your libraries at the location of your choice.

A suggestion for the placement of third party libraries (like for example the digikey library) is included in this screenshot. These third party libraries are added in the same manner as your personal libs. This tutorial will therefore not go into any more depth on them.

Adding a library to a library table

This section handles the additon of libraries that you already have on your disk. Creating new libraries is explained in great detail in separate FAQ articles:

The most powerful way to manage your libraries are the library managers found in the preference menus of all programs. Libraries can also be added using the add library buttons of the symbol and footprint editor.

Using the library manager

I show the symbol library manager in this section. The footprint library manager has the same user interface. Meaning you should be able to understand that tool without a special section about it.

The library managers are found in the preference menus of all KiCad sub programs and in the KiCad main window. (Menu entries are “Manage footprint libraries” and “Manage symbol libraries”. Only the main window shows both options. Sub programs show only the one relevant for them.)

The library managers are used to handle both the project local and the global library tables. Switch to the one you want to edit by selecting the appropriate tab. (Above the table view of the table entries.)

Use the browse button (looks similar to a typical open button in v5.1) to add libraries with a tool similar to a file browser. Navigate to the location of your libraries using this tool. You can use shift or crtl plus click to select multiple libraries.

You can also use the add button to add a single empty entry to the table.

Note: The “Path Substitutions” view in this dialog is not intended to be a duplicate list of the configure path tool. Its purpose is to give an easy way to see which substitutions are currently performed. To edit the variables or to see all available variables check the configure path tool found in the preference menu of every kicad subprogram.

Using the symbol or footprint editor add library menu entries

Both the symbol and footprint editor have an add library entry to the file menu, the top toolbar and as entry to the right click context menu in the treeview. (This is new in v5.1 for the footprint editor.)

Clicking this button will open a browser like tool that allows adding a library. You will be asked if you want to place the library into the local or global library table after selecting a file to add.

Appendix

Location of library tables within the file system

You should not need to edit the library tables with anything other than the library managers. You might however still benefit from at least knowing where they are found.

The global library tables is in the config directory of your operating system user.

  • Linux: The user’s home directory + .config/kicad (= $HOME/.config/kicad or ~/.config/kicad)
  • Windows XP: “C:\Documents and Settings\username\Application Data” + kicad (= %APPDATA%\kicad)
  • Windows Vista & later: “C:\Users\username\AppData\Roaming” + kicad (= %APPDATA%\kicad)
  • OSX: The user’s home directory + /Library/Preferences/kicad

The local library tables are found in the project directory.

Resetting the library tables to default settings

The current version of KiCad does not come with an automatic way to reset the library tables to the default settings (See feature request for “Reset lib tables to default”. There is however a workaround possible. Simply delete the library tables from the file system using your operating systems file browser. (A better option might be to rename them in a way that allows you to find them later if something goes wrong. For example add .backup to the filenames)

After that start-up KiCad. When starting pcb_new you will be informed that the default library table has been setup.
Starting eeschema will bring up a dialog asking if you want to copy the default library table, create an empty one or use a custom one. The default option will bring you back to factory settings.

If you do not get the default setting suggested then you do not have the library installed. A way to fix this is explained here: I installed KiCad 5 but there are no libraries. (The default option for sym lib table setup is disabled)


You could also download the library tables directly from github and manually overwrite the one in your config directory instead of deleting it.

You might even be able to only reset the entries belonging to the official library by using a text editor. This might however be more work than worth. (Adding your personal libs back should not be that hard if you have them all in one location.)

Updating the official library

KiCad does not update your personal settings on any update. This means you would miss out on libraries added after your first installation.

With the standard setup you can go with the normal reset to default options explained above.

When using the advanced setup with path variables setup you would need to overwrite the library table in your config directory with the ones you downloaded with the library.

Both of these will require you to add your personal libs back after doing this.


Another option would be to open the library tables with a text editor and remove any line defining a library of the official library. Then opening the library table shipped with your current version of the lib with the text editor and copying all lines (except the first and last one) into your library table in the config directory.

This really only pays of if you have many personal libs in different locations. (Adding any number of libs from a single location is easy) Or if you have descriptions added for your own libraries.

Options to download a particular library version (for the advanced setup)

Download zip archives from github

Every github repo can be downloaded at every release point and at the tip of the current master branch. The KiCad repos have a release corresponding to every KiCad release.

The releases can be found here:

Using a local git repository

Using a local git repository gives you more powerful options and can save on data volume as git only downloads what changed when you decide to get a newer version of the library.

You will need to understand a few git commands to use this way of downloading your libraries.

git clone [link to repo] (for getting the repo locally)
git pull (for getting the current state)


And possibly also git checkout [branch or tag] to switch to a particular release.
Checkout only works on the local repo. Meaning you might need to first download the current state of the online repo if you want to switch to a newer release. This is done with the git fetch command

Example (Checkout a release):

git fetch origin # to download the current state of the online repo
git checkout 5.0.2 # to get the library to the state tagged as 5.0.2

To find out which releases exist look under the release pages of the repos (see previous section for the links.)

Example 2 (get current head of master -> the development snapshot)

git checkout master # Switch to master branch.
git pull # Download current online state.

Project Local Libraries

It does not really make sense to rely only on project local libraries. The main downside of such a setup would be that you will have a harder time finding already existing assets. (Reuse becomes basically impossible as soon as you have more than a handful of projects.)

Even using project libs as a local cache might not really be the best idea. This could easily lead to having different versions of the same asset floating around in different project libs. (It increases the points at which you can introduce an additional error.) Let kicad take care of caching the assets used (footprints are included in the pcb file, symbols in the cache lib file)

3d models do not really play nice with a project local setup in the current version of kicad. (This is because footprints point directly to a file. Including 3d models would mean you need to edit the path settings inside of every footprint pointing to that model.) But 3d models are sadly not cached by kicad right now. Meaning make sure you do not change 3d models in the global lib without good reason.

Symbols with the footprint pre filled also play not nice when copying a global footprint to a project local library (Unless you keep the same footprint library name. -> This would however make it impossible to get any footprint from that global library in the future.)

Project specific symbols for micro controllers, connectors, power symbols, …

One usecase for project local libraries are project specific symbols for configurable parts. To get the best out of ERC you might want to specialize the electrical types of your connector and micro controller symbol pins. You might also want to specialize the pin names to make it clearer which alternative function to setup for a particular MCU pin or to make it easier to see what is connected to which connector pin.

Another use would be to have project specialized power symbols (To get better fitting net-names.) The reason for needing specialized symbols here is that the resulting net-name is controlled by the pin name of the symbol.

Archive a project for sharing with others (read only access)

Project local libraries can make sharing projects (for reading) easier as the reader does not need to setup libraries that way.

The reason why you would like to have at least symbol and 3d model libraries included in such an archive is because kicad does not reliably cache symbols and does not cache 3d models at all within the project files. (Symbols are only cached in the cache lib and rely on the reader using the rescue tool properly.)

A detailed explanation on how to archive projects is out of scope here. The short answer is that this is really only viable with scripts. See for example: https://github.com/MitjaNemec/Kicad_action_plugins/blob/master/archive_project/action_archive_project.py

How to setup a project with local libs

The suggestion for local libraries is to place them somewhere within the project file structure. (Placing them somewhere else will negate all benefits of project local libraries.)

The symbol (or footprint) libs would then be added to the project (local) library tables using the library manager. More details see above. (Instead of selecting the global library tab select the project library tab. Everything else stays the same.)

Make sure you use the path variable KIPRJMOD for project local libraries. It always points to project root. (The library managers should do this automatically.)

34 Likes
Library structure best practices
HELP! Libraries are not recognized (schematic symbols)
Ki-Cad Footprint for TX7-705, TDA21240,IR3897,IR3883MTRBF or IR3823
Add symbol screen
Adding a Connection Point
Help with custom symbol and footprint management
Enviromental variables vs library managers
No standard library included in kicad 5.1.6_1?
Need help making and saving footprints and symbols
Lost my Power Libraries!
Visualisation 3D
Problem with GitHub libraries
HELP! Libraries are not recognized (schematic symbols)
Can't save new Library on Mac OS 10.15.3 KiCad 5.1.5
When does a lib not allow editing
Library Management--how to "clean-up" without risking corruption?
Library Management--how to "clean-up" without risking corruption?
Errors were encountered loading footprints
How to share a sheet?
Browse all 3d models for a family?
Problems installing kicad libraries under manjaro linux (arch derivate)
How to add footprint programmatically
Manage Footprint Libraries causes Kicad to crash
Eschema ask for a not (anymore) existing Library file
FootPrint Paths and Folders
FootPrint Paths and Folders
[SOLVED] Logos/Drawings in Eeschema
Adding Components
How to get from SN74AVC8T245 to SN74LVC4245A?
Schematic Symbols entry with no schematic symbol
Relocation of library files
Error loading footprint 2
User Path Configuration
Scripting EEschema and NGspice, general Questions
Issues with version control of project specific libraries
Lost in Kicad libraries
Lost in Kicad libraries
Component Library Help File (v5.1.5)
Modified/Editied footprint after running PCBnew
No footprint assigned
3rd Party Library Installation on Old Mac
Create new power symbol from a existing one
How to export all components from schematic to a library
3D question-what files do I need?
Team PCB projects, best library/workflow practices?
Configure Global Symbol/Footprint Library Table
Newb here, library loader, no footprint
Make library active in kicad 5?
Problem in invoking footprint editor in KiCad V5
Managing Libraries in KiCAD (MacOS)
Libraries on Schematic are empty - Windows 10
My symbols gone, how to re-add them
Wrl file vs step file for 3D model of part
Can't find digi-key components
Can I Save a 5.1.4 project then open it in 4.7
How to get a downloaded symbol, footprint or full library into KiCad version 5?
Internally connected VCC
Symbol Libaries are not installing when I install KiCAD
How to version control kicad with google drive
Footprints in Kicad 5
Power ports ... where are they?
Windows10 create shared libraries under C:\Users\Public\Public Documents\KiCadLocalLibs
Upgrading from 4 to 5: any hints and tips
[SOLVED] How to globally put component pads on B.Cu back copper only?
Configure Paths
No symbols in Eeschema
Opening schematic in another PC
Searching for the symbol of TDA1562
Assign footprint to symbol removes symbol
Importing project libraries
KISYSMOD and KISYS3DMOD
Kicad lose symbols
Symbols not present
Can't store new footprint in library [read only error]
Using Git with the KiCAD Libraries
How to organize libs and modules
Adding FST3253 Switch to PCB
Beginner's guide to KiCad
Added environment variable not appearing in Manage Symbol Libaries path list
Adding spice components that do not exist in pspice library
How to use current controlled switch (WXXXX) in kicad eeschema
Sharing 3D models across Mac (or Linux) and Windows machines
Copper Pour Ain't Filling
Another Cry for Help With Empty Footprint Libraries
Add Library Folder
Path Substitutions won't show up in the Symbol Libraries window
How do I choose the right footprint?
Eeschema "The following libraries were not found"
Add default libraries to library table
Pin headers are rotated
Housing_LCC PLCC-44_THT-Socket is not usable in 5.x
Lib-table file locations on linux & windows & mac
Fighting for weeks around libraries
I am confused about 5.1 libraries in MacOS
KiCAD 5.1.2 Footprint Editor
How to load default footprint library
PcbNew doesn't find footprints I just assigned in CvPcb
Having trouble with library install
Location of User Global Libraries by Symbol Editor
Including a 3rd party GitHub library
Running several KiCad versions on the same Windows machine
KiCad not able to find symbols when trying to open project on another PC
How to specify paths to footprint labraries
Running a New and Very Old KiCad Versions
Accessing libs in Kicad
Legacy .mod files and KiCad V5.1.0
I have a library problem!
I want to load multiple symbol libraries at once
Storing stp files
Using kicad on 2 different PCs
Annoying broken footprint
First PCB: Simple DIY Ambilight
More fully specified symbol library discussion
Kicad Installation
3D models and library management
Upgrading from 5.0 to 5.1 - any issues foreseen?
Associating 3D shapes by default
Resistor lib, what am I missing
Something wrong... what is Question mark(box)?
Rats nest not updating and schematic components absent from Layout
Help With Library Oganization
Kicad seem to "forget" 3D models
My library in new release 5.1.0
Could not find any symbols
Preferences -> Component Library Not Found
Dealing with library shakedown
Lost all global libraries (SOLVED)
Path configuration
Library contribution style guide, preserving custom parts in KiCAD libraries
Switching Computers, Setting Up KiCAD fresh
Path configuration
3D view of pin headers is skewed
AirWires not showing in pcbnew
Setting up v5 on a mac
Libraries not loaded
KiCad 3d Models auto update
Failed: GET command from GitHub KiCad libraries
Schematic Libraries 5.0.2 problem
KiCad 5 on my Mac can't find footprints
Cannot open KiCad 5 footprints with footprint editor
Cannot open KiCad 5 footprints with footprint editor
librairie personnelle
Env variable in Spice Model Library field?
[SOLVED] Deleting Library
Migrating from KiCad4 to KiCad5.0 and 5.1
Kicad 5.01- Installation- can't locate libraries
Kicad 5.01- Installation- can't locate libraries
Problems with KiCAD v5 on Mac
Git and the libraries for newbies
Where is JFET footprint?
Kicad Footprint Library Issues
[solved] Songle Power Relay 3d library
Creating New Footprint from Github Text
Kicad 5.0.2 Module Setup
Standard-symbols missing in KiCAD5.0.2 on LINUX-Mint
Help Saving a Footprint
Lost access to my folder
3D models not showing
Why such bad documentation?
GitHub Tutorials For Noobs?
Adding a logo with the conversion tool
Tutorial: How to make a symbol (KiCad v5.1.x)
I had KiCad 4 installed previosly. Now i updated to v5. Now i have some problems with the library setup
Linux version - Part Library Editor - can't write to libraries
HELP! Libraries are not recognized (schematic symbols)
Best practice for editing symbols/footprints
Save schematic components to library
Environment Variable can't be set to §{KIPRJMOD}
Multiple symbol library paths
Broken installation
How to backup component library
Schematic Symbols disappear all the time (KiCad unusable)
Project and libary setup for sharing and collaboration (KiCad version 5)
I come from Eagle. What should i know about KiCad?
Error in loading footprint
Best practices for libraries with Git 6.0.7 Linux
Schematic Library load issue - help appreciated
Loosing schematic library symbols
KiCAD LIBRARIES
How to convert a schematic built into a PCB built on MacBook?
Project and libary setup for sharing and collaboration (KiCad version 5)
macOS Catalina Installation
Libraries multiple access
Missing footprints kicad 5.1.8
Symbol for UM3561
How to change pads and their holes, globally?
Load Symbol Library from Python Script
No symbol found in library
Adding footprint libs
Where is stored the list of libraries and the path
Ki cad software
Noob question about New Library Symbols
New to making symbols for eeschema and pcbnew
Footprint libraries are on folder but doesn't appear in footprint editor
Project Specific Libraries on MacOS
No symbols found
No footprints in library
I can't save my schematics on MAC
Can't open projects I downloaded. Issues with library
Upgrade Frustrations - libraries
Tutorial: How to make a footprint in KiCad 5.1.x?
Default to paths relative to `${KIPRJMOD}`
No footprints for symbols kicad 5.99 - Stock library
Changed to new pc, cannot see 3D models in 3D viewer
Mac OS Catalina Installation
I installed KiCad 5 but there are no libraries. (The default option for sym lib table setup is disabled)
Libraries are not found!
User Symbol and Footprint Libraries
Graphics crash while saving symbols
How do you create a symbol library that works?
Kicad6 installation process and why the Kicad experience generally tends to suck
How do you create a symbol library that works?
[SOLVED] Footprint for EL817S1 (SMD version of EL817 / PC817 opto coupler)
Kicad library in linux mint
Versioning Configure Paths Environment Variables
Can I change hole size? (but, more complicated?)
Insert footprint to module, from standard library
MOSFET not available in library
Saving modified symbols
On ver. 5.1.10 cannot place symbol for transistor
What is the relationship between the .lib files?
Symbols Library missing in kicad
Pin connected to some others pins but no pin to drive it [for VSS and VDD]
V6 No Libraries available
Save a new symbol
Getting Started step 50: footprints not getting linked to symbols
After upgrade to Kicad 7 all system libraries are lost
No footprint selected
KiCad 6 install on LinuxMint symbols fail (SOLVED)!
How can i install a specific version of the footprint library?
Kicad 5.0.2 Module Setup
(Start Here) Frequently Asked Questions
Library Conflicts Between Users? How to Solve?
HELP! Libraries are not recognized (schematic symbols)
Some footprint libraries not appearing? (help?)
Libraries are missing
Adding 8 Pin DIP socket
How to organize libs and modules
All libraries missing in Symbol Library Browser after MacOS install
Questions from a newbie
EEschema - How to modify Library Symbols
Kicad6 installation process and why the Kicad experience generally tends to suck
Strict limit to local libraries
Can't assign footprints
[Bug?] All global symbol and footprint libraries are missing from editors
Configure Paths
Component or Symbol?
Library missing when project files copied into another system
AirWires not showing in pcbnew
Confuration Error (Win7 64bit/Lastest Kicad version)
KiCad not able to find symbols when trying to open project on another PC