How can i install a specific version of the footprint library?

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.

8 Likes

Using the new KiCad 5 library with KiCad version 4

As stated above the new lib is allowed to contain footprints with pad shapes incompatible with version 4. The library team did however release a backport for the v5.0.0 library which is compatible with version 4 (it has a slightly reduced number of footprints) https://github.com/KiCad/kicad-footprints/releases/tag/v4-backport-5.0.0

For any other version of the new official library (or for third party libs) one would need to create the backport manually. (Later versions of the version 5 library will not be so easily backported as rounded rectangle pads will be used in more footprints.)
To be able to at least use all valid footprints one can remove (or manually edit) incompatible files.
A script that lists and optionally removes all incompatible files has been developed: check_kicad4_incompatible

Sadly the script right now does not check for the new 3d model offset field. So some manual work might be required if you have 3d models with offset different to 0,0,0. (0 offset is stored backwards compatible by kicad. The official lib does not allow offsets differing to this so we have no need to include this in the script)

4 Likes

Easy way to get local libs in KiCad 4 but without control which version gets installed

If you do not care what version of the KiCad 4 libs is used, then you can use the library wizard and the github plugin with save local on disk. (This will simply be the copy of the current HEAD of the master branch. Updating will not be necessary as the version 4 lib is no longer maintained.)

More details in this tutorial by @bobc: https://github.com/bobc/kicad-doc/wiki/How-to-install-local-Footprint-libraries

1 Like