Disclaimer: This article is mainly aimed at explaining how to work with the library in version 4. For version 5 the Library management in KiCad version 5 FAQ article might be a better read.
The official documentation about this can be found under: http://docs.kicad.org/stable/en/cvpcb.html#_footprint_libraries_management
Introduction
KiCad Version 4.0.x
The default installation of KiCad 4.0.x on most operating systems is setup to use on demand online libs. (github plugin)
This setup gives the user no control over which version of the library they use. (The footprints are downloaded on demand directly from github.)
Another problem that results from the use of the github plugin is that each library must be placed in a separate repository. This fact makes it hard to manually download a specific library version.
Luckily there are snapshot archives downloadable from: http://downloads.kicad.org/libraries/ (There are two different downloadable archives per release. One holds only footprint libs the other holds the symbol libs, 3d models and templates)
There is also another option. You can use the library download script https://github.com/KiCad/kicad-library-utils/blob/master/download_pretty_libs.py
This script does use git to clone the official repos to a local location. It also allows you to checkout a specific tag (=release)
You can even create your own tags and check them out later.
KiCad Version 5
For KiCad version 5 a large library reorganization took place. One of the main changes is that all footprint libs are now located in a new kicad-footprints repository.
This allows easier use of git and the download options by github. (It does however break the github plugin.)
In addition to this there is also the new library download page as part of the official KiCad website: http://kicad.org/libraries/download/ (direct link to the footprint download page: https://kicad.github.io/footprints/)
The version 5 libs are not guaranteed to work with KiCad v4.0.x. In particular these libs might include footprints with roundrect or polygon pads. Any lib containing at least one incompatible footprint can not be used with KiCad version 4. (See further below on how you can still use at least the compatible footprints.)
Installation of the libraries
No matter what library version you want to install, you will need to point KiCad to it.
The first step is to download the library or libraries of your choice.
For the best user experience it is suggested to install the symbol and 3d libs of the same version as well.
If necessary extract them from the archive they come in.
Using the unofficial package installer
@bobc wrote a python script that can help installing data packages for kicad. It should be able to handle libraries: Announcing KiCad Package Installer - kipi
Where should i install the libs?
Put them somewhere convenient. Some place where your user of your operating system has write access. For a multi user setup choose a location that at least provides read access to all users.
An example would be to place them within the users home directory.
Note: The KiCad installers put the libs into system directories. It is not necessary to do it that way. If you have the option put them somewhere where you do not need root (or admin) access.
The fp-lib-table
KiCad holds the information about installed libs in so called fp-lib-table files.
There is a global fp-lib-table located in the home directory of the 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
Each project also contains a local fp-lib-table in the project directory. (If it has at least one local footprint library.)
Add libs to the fp-lib-table using the library wizard. (KiCad version 4 only)
This is the easy workflow.
As a first step you will need to delete all entries from the fp-lib-table using the footprint library manager. (You don’t need to remove entries corresponding to your personal libs.)
This tool is found in the preferences menu of pcb_new or the footprint editor.
(You can also use a text editor for this step.)
After you cleaned up the fp-lib-table you can start adding the libs you downloaded.
Start the footprint library wizard found in the preferences menu of pcb_new or the footprint editor.
Select “Files on my computer” and press next.
On the next page navigate to your library location and select all .pretty directories (=libs) you want to add. (If you want to add all of them: click on the first, scroll down to the last and shift click on it. You can also use ctrl+click to select only specific libs.)
Click next as soon as you selected the libs you want to add.
Now KiCad will run a validation process and report its results back to you. (If any of the libs is invalid you might have downloaded libs intended for a newer version of kicad.)
On the last page of the dialog you will be asked if you want to add the libs to the local or global lib table. For most applications the best choice to add the official libs is the global lib table.
Using the library manager to add libraries (KiCad version 5)
Adding libraries that you already have on your local hard drive is quite easy using the library manager.
To start the addition process use the browse button. This will open a tool similar to a file browser. Navigate to the location of your libraries and select all libs (.pretty directoris) you want to add (shift plus click and crtl plus click allow for selecting multiple libraries)
Making use of environment variables
Kicad does support app defined environment variables. They can be managed from the “Configure paths” tool found in the preferences menu of the main window.
Environment variable names are limited to Uppercase letters plus underscore. (Any invalid char will be ignored without visual feedback. -> to the user it looks like the input field does not work.)
These environment variables can be used within the lib tables and even within the 3d model path of a footprint.
The syntax to use such a variable is as follows: ${VARIABLE_NAME}
To add environment variables to the lib table use either the library manager or a text editor.
Use the fp-lib-table supplied with the lib (v5 only)
This workflow is for advanced users. Before doing anything bacup your old fp-lib-table in case you screw it up.
The library for version 5 already includes a fp-lib-table. To use it, you must copy its content into the global fp-lib-table by using a text editor. If you already had a previous version of the lib added you might need to first remove the old entries. (Or you only need to add only entries for new libs.)
This fp-lib-table does use the environment variable KISYSMOD to find the installation location of your libs. Editing this variable is done using the configure paths tool found inside the preferences menu of the KiCad main window.
This workflow allows you to use multiple versions of the library at the same time. Simply change the environment variable to point to the library version you currently want to be used.