Skip to content
This repository has been archived by the owner. It is now read-only.
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

Upgrading from Version 4 to Version 5

Changes were made to the behavior to KiCad during the version 5 development that can impact projects created with older versions of KiCad. This section serves as a guide to ensure the smoothest possible path when upgrading to version 5 of KiCad.

Schematic Symbol Libraries

Schematic symbol libraries are no longer accessed using a symbol (referred to as components in version 4) look up list. Symbol libraries are now managed by a symbol library table that behaves similarly to the footprint library table. This change is a significant improvement, but some schematics may need manual intervention when being converted to version 5.

In previous versions, KiCad used a list of library files to search when locating symbols in the Eeschema file. When locating a symbol, each path would be searched and the first library that held the symbol name would be used.

From v5, KiCad symbol names are prefixed with a nickname, and a lookup table matching nicknames to library paths is used to locate the library which holds the symbol. The table is called the 'symbol library table' and built from configuration files stored in the user’s KiCad configuration directory and the currently loaded project directory.

To upgrade a KiCad project from v4 to v5, nicknames for all of the library files need to be created and then schematic symbol names need to be prefixed with the correct nickname.

Global Symbol Library Table.

Eeschema v5 will automatically create a global symbol table when first started. You will be given a chance to skip this and create your own global symbol table by hand. You only need to do this if don’t use KiCad symbol libraries at all. Otherwise it is easier to modify the automatically generated global symbol table.

If you track the symbol library repository, changes made to the default global symbol library table are not tracked by KiCad. You will have to manually keep the global symbol library table up to date.

Symbol Library Table Mapping

Automatic remapping of symbols will be executed whenever a schematic is opened that has not been remapped. There are a few steps you should take ahead of time in order for the remapping to be the most effective.

If you have been using a development build of KiCad, copy the full default global symbol library table file (sym-lib-table) from the template folder installed with the KiCad libraries or from the KiCad library repo to your KiCad user configuration folder. This will replace the empty one (most likely) created by Eeschema. If you do not do this, you will most likely end up with a bunch of broken symbol links.
Remapped schematics will not be compatible with older versions of KiCad. The Remap Symbols dialog will make a backup of your schematic files and you should do the same if you remap manually.
  1. If possible, keep version 4 of KiCad installed on your system unless you have never used any of the symbol libraries distributed with KiCad.

  2. If you get warning about missing libraries when you start version 4 of Eeschema, make sure to fix the missing libraries if they contain symbols that are in the schematic before you attempt to remap your schematic. Otherwise, the correct symbol will not be found and you will end up with broken symbol links in your schematic. You can test this by left clicking on a symbol in the schematic and verifying that the symbol is not being loaded from the cache library. If a symbol is being loaded from the cache library, Eeschema cannot find your part in the system or project symbol libraries. If you need a cached part to be available to other projects on your system, you will need to integrate it into a system or project library manually.

  3. If symbol recovery is required during the remapping process, do not dismiss it. Failure to recover symbols will result in broken symbol links or the wrong symbol being linked in the schematic.

  4. During the remapping process, symbol libraries not found in the global symbol library table will be used to create a project specific symbol library table. You can move them manually to the global symbol library table if that is your preference.

  5. For the most accurate remapping, create a project library by copying the project cache file (project-name-cache.lib) to a different file and add it to the top of the symbol library list. You must use a version of KiCad prior to the symbol library table implementation in order to do this.

Fixing broken remapping:
A tool has been provided to attempt to fix remapping issues. If there are missing symbol library links in a schematic, they can be fixed by opening the "Tools→Edit Symbol Library References…​" menu entry and clicking on the "Map Orphans" button.

Remapping Search Order

When remapping symbols, KiCad proceeds in the following order to assign the library to a symbol:

  1. Global Symbol Library Table: Symbols are preferentially mapped to the global symbol library table, if one exists.

  2. Project specific libraries: Libraries listed in the project library list that are not in the global symbol library table are searched next.

  3. Project cache file: If a symbol doesn’t exist in the listed libraries above, it is first rescued — a copy is made from the cache and placed in the proj-rescue.lib — before the symbol is mapped to this new, rescue library.

Symbol Names and Symbol Library Nickname Limitations

Symbol names may not contain <SPACE>, ':', '/'.

Library nicknames may not contain <SPACE>, ':'.

Existing symbol names with these characters must be renamed by manually editing the relevant schematic and library files.

Symbol Cache Library Availability

The cache library is no longer shown in either the symbol library viewer or the symbol library editor. The cache should never be edited because any changes are overwritten by the next schematic save.

Board File Format Changes

Several new features have been added to Pcbnew which impact the board file format. Using these new features in board designs will prevent them from being opened with previous versions of Pcbnew.

  • Rounded rectangle footprint pads.

  • Custom shape footprint pads.

  • Footprint pad names longer than four characters.

  • Keep out zones on more than a single layer.

  • 3D models offset saved as millimeters instead of inches.

  • Footprint text locking.

Global Footprint Library Table.

If you track the footprint library repository, changes made to the default global footprint library table are not tracked by KiCad. You will have to manually keep the global footprint library table up to date.