KiCAD Best Practices: Library Management

One common complaint we hear from most new KiCAD users relates to schematic and footprint libraries. The trick is to use just one schematic symbol and footprint library each with your project. This way any changes to the default schematic libraries will not affect your project and it will be easy to share your project with others without breaking it. I’ve spent some time refining this technique and I’ll walk you through the process in this article.

We have covered KiCAD (as well as other) Electronic Design Automation (EDA) tools several times in the past. [Brian Benchoff] did a whole series on building a project from start to finish using all the various EDA packages he could lay his hands on. No CAD or EDA software is perfect, and a user has to learn to get to grips with the idiosyncrasies of whichever program they decide to use. This usually leads to a lot of cussing and hair pulling during the initial stages when one can’t figure out “How the hell do I do that?”, especially from new converts who are used to doing things differently.

Read on to learn the best practices to use when using KiCAD and its library management.

Project Management

KiCAD keeps schematic symbols and component footprints in separate libraries and you need to link a symbol to a footprint using one of several different methods. This puts off a lot of folks, but it works quite well once you get used to it.

In the old days before computers, most designers would first quickly draw out a schematic, then create a “bill of materials” where they flesh out the specifications of the components to be used. This would then help them to choose the component footprints, leading to the board layout phase. KiCAD tries to follow this work-flow. Here’s a typical folder structure I use to organize a KiCAD project, having refined this technique over many years of working with the software.

 ↳3d_models     // .STEP and .WRL model files for all footprints
 ↳datasheets    // data sheets for components used
 ↳gerber        // final production files
 ↳images        // SVG images and 3D board renders
 ↳lib_sch       // schematic symbols
 ↳lib_fp.pretty // footprints
 ↳pdf           // schematics, board layouts, dimension drawings

Managing Schematic Libraries

When you draw a schematic using symbols from the built-in libraries bundled with KiCAD, EESCHEMA creates a local backup library — doodad-cache.lib. Once you’re done drawing your schematic, copy this file to the ↳lib_sch folder  and rename it to doodad.lib.

Next, go to ↳PREFERENCES↳Component Libraries , select “CURRENT SEARCH PATH LIST” to point to your local project folder ~/doodad/, click the ADD button at the TOP of the pop up window (NOT the Add button in the middle of the pop up), and finally select doodad.lib. It gets added below the currently selected library in the list.

KiCAD reads these libraries in sequential order, so you need to select doodad.lib and bring it to the top of the list using the UP button. If there’s a symbol with the same name in different libraries, then the first instance of it gets used. At this point, you can either remove all the other listed libraries, or just ignore them as long as you ensure that every symbol you use gets added to doodad.lib and get’s called only from that file.

Your project now uses just one schematic symbol library — ~/doodad/lib_sch/doodad.lib — and any changes to the default schematic libraries will not affect your project. Moreover, using the above defined folder structure, it’s easy to share your project on GitHub. When your project gets cloned or downloaded, this ensures there are no library conflicts.

All of the above may change when KiCAD implements s-expression formats in EESCHEMA and schematic libraries (already implemented in PCBnew), so we’ll revisit this at that time.

Assigning Footprints to Symbols

There’s several ways of doing this, but essentially, you select a schematic symbol, and assign it a footprint from one of the default libraries. Ever since KiCAD moved footprint libraries to GitHub, this has been a cause of heartburn for many. For one, all libraries are hosted online, and KiCAD needs to look them up every time you fire it up. For those who don’t change this behaviour, it slows down the program during startup, if you’re not connected to the web. Online libraries are a good idea because footprints stay updated, but it is a sure fire way to break your designs should one of the footprints used in your design change. This won’t show up for you immediately, because you will have to explicitly re-read the net-list and get KiCAD to replace changed footprints. But for someone else who clones your design, and their KiCAD version loads up the updated footprint, it WILL break things.

The solution is to clone all the KiCAD libraries to a local location on your computer, and then point KiCAD to this location. But when you do this, it negates the advantage of having access to updated libraries. I don’t think there’s an ideal way to make it work, but here’s what works for me.

I clone the GitHub libraries to my local computer, and keep them updated by regular pulls. This helps me use existing footprints or modify them to suit my requirements. But my project does not use any of those cloned libraries directly. Instead, I generate a project specific footprint library that contains all of the footprints (~/doodad/lib_fp.pretty) used in the project. Once again, this ensures that when the project gets cloned, all of the right footprints are already available without depending on external source libraries.

How to Make KiCAD Footprints Local and Project-Unique

Start by cloning (from GitHub) the KiCAD footprint repository to your computer. This is best done using the ‘Footprint Libraries Wizard‘ from within PCBnew. In my case, I have cloned it to ~/kicad_sources/library-repos. In KiCAD’s PCBnew, select ↳PREFERENCES ↳CONFIGURE PATHS and edit KISYSMOD to point to the local footprint library path (~/kicad_sources/library-repos).

path to fp-lib-table

In some cases, additional steps may be required to make things work. Select  ↳PREFERENCES ↳FOOTPRINT LIBRARIES MANAGER and determine the location of the “fp-lib-table” file used by PCBnew. This is a text file that tells PCBnew where to look for footprint libraries – on Github, local path etc. Open this file in a text editor, and check if it uses KISYSMOD as the path. If not, do a search and replace for all instances of current path and replace it with KISYSMOD.

Now, you can edit each schematic symbol, and add a footprint to it — either from within EESCHEMA, or using the stand alone Cvpcb module. Once all footprints have been assigned, make sure you re-generate the netlist before moving on to PCBnew.

MODE : footprint
MODE : footprint

You can now start PCBnew and read the netlist, which dumps all the footprints in a pile on the canvas. Select the Mode : footprint icon, then context-click on any ONE footprint, select ↳Global Spread and Place ↳Spread out all footprints.

This spreads out all the footprints making it easier to select and move them around. Once you’re done with your board layout, and all of your footprints are locked in, select FILE ↳Archive Footprints↳Create Library and Archive Footprints and provide the path/name to the .pretty folder in your project (~/doodad/lib_fp.pretty). This copies all the footprints used in your layout to the target folder.

Then, Preferences↳Footprint Libraries Wizard↳Files on my computer↳(navigate to ~/doodad/lib_fp.pretty) and make sure you select “To the Current Project Only” before hitting Finish. At this point, you have used footprints from KiCAD’s global libraries and applied them to schematic symbols, made a netlist, imported netlist in PCBnew, placed the footprints and routed the board, made an archive of all the footprints used, and configured PCBnew to use that archive library.

Replace Library paths

Next, return back to EESCHEMA, and edit the footprint association of each symbol to point to the new lib_fp.pretty folder instead of the local GitHub repository on your computer. The easiest way to do this is to open the .SCH file in a text editor and do a search/replace. In our present example, we will replace instances such as “Capacitors_ThroughHole” or “Resistors_ThroughHole” or “LEDs” with our local project library folder “lib_fp”

Open the schematic one last time, save a fresh netlist, open PCBnew, read this netlist, but this time select the CHANGE option under Exchange Footprint. Your board layout will now be using footprints saved in your lib_fp.pretty folder, and changes to the KiCAD global libraries will not affect the layout.


This may sound a bit convoluted in the beginning, but over time it becomes quite easy, and you can eliminate some steps as you get better. For example, I already have my own library for most of the common parts that I use, and copy these footprints before starting off on a new project. Over time, as you get better at it, you will start building your own schematic symbols and footprints from component data sheets instead of using external versions. Like I said at the beginning, it’s not perfect, and for me this process works very well. If you have comments or suggestions on making this better, chime in and let us know.

34 thoughts on “KiCAD Best Practices: Library Management

  1. I haven’t found any CAD package with what I’d consider good component management. If you create or download a part, you need to decide what file and directory to put it in. If, for example, it’s a PIC microcontroller, do you put it in the Microchip file that’s distributed with the software (in which case it’ll be overwritten when you download a new version) or do you put it in your own file (in which case you have a Microchip part that’s not in your Microchip library and it’s hard to find).

    If I then want to distribute my circuit design, how do I distribute the parts I created? How does someone incorporate those parts into their library? There’s no standard and it’s not easy.

    There’s also no parameterized searching. Maybe I’m looking for a PIC chip in a QFP64 package. There’s no way to do a search like that.

    Let’s say I download two different parts libraries from the web, and they have an identical part. How do I resolve duplicates? How do I even know there are duplicates? How do I know what other parts are in the libraries that I might find useful? How do I remember that 3 months from now?

    In short, file-based parts libraries stink. There needs to be a database system. In my crazy moments, I dream of forking KiCad and developing one, but then I come to my senses.

    1. “I haven’t found any CAD package with what I’d consider good component management.” I concur, I use Altium at my fulltime job and KiCAD for after hour shenanigans. While Altium does it a bit better, I feel like no one has good library management tools. Fortunately KiCAD is open and has a python scripting engine, so I hope to develop my own library management tools and release them on github.

      Another problem that makes all this worse is how you plan to organize your libraries. At work components are sorted by type and function where as my libraries are related to either a specific board or family of boards, everything for the given board or collection of baords all in one lib. The later way makes component placement in a schematic take less mouse clicks but gets disorganized when the library now pertains to like 15 different 4 layer boards LOL

      1. I feel like this is a solved problem and we’re just re-implementing the wheel all over again. Instead of the folders and files metaphor we need to use tags. For instance, this “new component downloaded from the internet” that’s a pic. Would have some of its tags be: “SMD”,”PIC”,”16bit”,”QFP64″. For example.

        Of course the metadata would be put into something like sqlite and you could throw SQL statements at it.

      2. KiCAD libs are able to take ‘tags’ already and you can type them into a search field and it will only list what has those tags in it.. the same works if you start typing component names.
        The latest nightlies admittedly do an even better job at this.

  2. KiCAD has always made creating and maintaining new library parts far too difficult, this is its true downfall. I ALWAYS had path issues after moving board files to another computer or trying to consolidate my parts into one library. I have since moved to Eagle and have ZERO problems with their parts library system. But now that Eagle was purchased by Autodesk and greedy hands moved it to a monthly billing model I may consider moving back.

    1. I’m in the same boat. The scheme Eagle uses to store the referenced version of the sumbol and footprint in the board files themselves is really the ideal way to handle this problem. If you want to update the current file’s part symbol or footprint, you specifically have to hit a button! And there are never discontinuities in any board file wrt to a part library.

      While I see the cliff approaching for Eagle due to the horrific licensing scheme, KiCAD has to improve in areas like this otherwise no amount of candy coating will make the pill easier to swallow. :(

      1. I have switched to Kicad a couple of years ago and Am still hammering the fact that the devs seem to do library management wrong, depending default on the github libs. what could be more wrong than that? in the default setup you build boards based on parts which could (and will) change by someone else on a inconvenient time. I suggested a copying scheme were parts are copied to the project from any place (including the github libs) and stay consistent with the board unless the user decides to update them.

        Now i have a library folder containing everything i use and if a part or footprint is used and confirmed, it will be transfered to my own private library. Of course I only use parts and footprints of my own library.

        TLDR: there should be a easy copy system to move parts and footprints to other libraries. Now i use the filebrowser and a text editor to do so

        1. Github libs being changed is not an issue with your board. This is because there is a cache of footprints in the project and it will only swap footprints for new ones if you explicitly check this when you load the netlist. So the issue you seem to be worried about does not occur.

          1. yes, this. The component and footprint cache in each project is a great thing, and it solves (better!) the problem of sharing that Anool seems to be trying to solve by having per-project libraries.

            Much better, IMHO, to have your own dedicated libraries, organised however you want. Make use of the components in projects, and then when you publish the project to github, it will contain its cache. It seems there is no need to also export the component or footprint libraries unless you want contributors to edit them also.

          2. Its not pcbnew, its eeschema fucking things up. and as pcbnew uses netlists generated with eeschema…

            ok. consider this scenario:

            you made a board with lots of parts and after a year you change something in the schematic. In the mean time the polarity of a diode changed from lets say k=1 to k=2. eeschema changes that automatically so your schematic has all its diodes reversed. you generate a new netlist and on the board the polarity of your diodes is also reversed.

            Basically a IDE should be avoid of automatic updates of whatever. if something is update, I should be the one to initiate it.

        2. “you made a board with lots of parts and after a year you change something in the schematic. In the mean time the polarity of a diode changed from lets say k=1 to k=2. eeschema changes that automatically”
          No, EEschema doesn’t change anything ‘automatically’.

          If your global component lib (symbols) changes and you load an old project, EEschema will aks you if you want to rescue symbols or if you want to use the new ones.
          Your project folder contains a .cache-lib file with all the symbols you use in your schematic when you make it.
          That’s the lib that is being used for the rescue operation – or to put it more bluntly – if EEschema finds that the symbols in that lib deviate from the ones in your current global libs, it will ask you which ones you want o keep in your currents project schematic.
          If you say ‘rescue’ it will use the ones in the .cache-lib and create a .rescue-lib in your project folder and this will be the topmost lib for symbols then in your schematic.
          If you opt for not ‘rescuing’ all the deviating old symbols will be replaced with the new ones and you potentially screw up your schematic and later on your netlist.

          To understand this I’d suggest to red this:

          The newest developer versions now contain the basics for the same system that the footprints use already.
          I can see a sym-lib-table in the ini-folder of KiCAD these days, so at some point the whole ‘rescue’ stuff will be gone.

      2. Exactly. My favorite thing about eagle (which is still a late added feature) was to be able to open the new and old design and copy a part from there to there. I had a design, I made it, it worked, that is where I want to go and fetch that part from.
        Can’t copy paste from 2 designs in KiCad (last time I used it).

    2. I have been using Design Spark for five years now, made several boards and it is fine. Still some library quirks, as you’d expect. But not nearly as goofy and unorganized as KiCAD. I moved to try KiCAD so that I could work on projects from any of my PC’s, Linux or Windows. I’m still a believer but the library storage system is just not intuitive, except for the person that wrote it.

    3. You might want to put some dates on your experiences as KiCAD is evolving all the time.
      Things which might have been true just 18 months ago don’t apply to the latest developer version anymore.

  3. The component library workflow seems OK to me, the footprint library import wizard is a bit more painful to use. However to me to worst part is editing part parameters which is a nightmare. I wish there was integration with Octopart to fetch parameter data automatically like Altium does, otherwise generating a quality BOM sheet could take many hours of manual labor.

    1. I disagree. the eeschema parts are the most dynamic ones in the whole kicad world (as for now. it seems that things will change there in the very near future). Dont look surprised that pins of diodes change because you included a library higher in the hierarchy for a certain part, but that lib included a wrong diode pinout…

      bit me once in a batch of 100+ boards but the prototype was fine. :-(

      1. This tool looks super cool. I couldn’t find any documentation on how to use it, though. I’m assuming it needs to be built from source using QtCreator?

        I’ve never built apps from source before, and my cursory web search didn’t turn up much. Would you happen to have any links describing the process for doing this for macOS/OSX?

  4. Does anyone create one library per component? It may get a bit messy for large projects, but with the right naming conventions and folder structure, it may make it simpler to share components between projects since you could just copy the component libraries needed for that project. Up till now I’ve just been using the one library per project approach.

    1. I will probably ( provided some day I can learn how to use Kicad instead of just the pullin hair and cussing at the developers ) create a couple libraries, grouping similar components. Discretes, families of ICs, etc. More of a personal preference, but makes easier to find
      componentes .

    2. I do, mostly. It is because the parts that I need to make a footprint/symbol for are not usual. Also it is better to send somebody specifically that part if they ask for it instead of a big lib where I need to explain all the crap that is there.

  5. Altium….

    Parts can contain, Schematic symbol, footprint, spice model, 3D model, any tags that you’d like to add, a really useful Vendor Part Lookup that parses all of the part’s pertinent information into the part.

    That’s not even the vault part.

  6. That’s the way many ECAD programs do it by default. They automatically create a project library, when you start a new project.
    For every symbol and footprint you add, a snapshot will be copied to the project library.
    When you open a schematic or layout, the program will warn you about changes in the global library. Depending on brand and settings, this may be a popup, a logfile, or some sort of markings on the screen.
    You can then decide, whether to stay with the current part, or update it. Should the update break something, you can always undo it.
    That’s the way it should be done.

    1. You don’t even need snapshot. Libraries are on git, which mean there is a sha-1 somewhere. So when opening project, use the correct sha-1 and not the HEAD.
      Using git for storage and not even properly use it is just pure laziness.

    2. And tada, KiCAD does it that way.

      The snapshot for symbols (components in KiCAD speak) are in a .cache-lib file and the footprint snaps are in the .kicad-pcb file.
      In the future (probably _not_ next release in Q3/17) the system for the symbols will change to be similar to the footprint system and the snapshots will be part of the .sch file, but that’s not now.
      The reason for why there is currently a different behaviors is here:

  7. I have been finding it difficult to work with the library system, so I appreciate this post. Thank you.

    In my search for help, I found an open source KiCAD library manager that someone is working on that makes it easy to manage the libraries and files. I haven’t tried it yet, but it looks promising. I hope the KiCAD community can join in on the efforts to accelerate its progress, but it seems to be fully functional. Below are some details and links.

    It is called KiCAD Librarian and it is open source and on github. It can do the following:

    – easily manage the files and folders
    – compare and easily edit footprints
    – works with symbols and 3D models

    Here are some links:

    Web Site:


    KiCad Librarian Snapshot:

    Video Demo:

    Not sure if this site automatically creates links, so here is the HTML for the links:

    Web Site:


    KiCad Librarian Snapshot:

    Video Demo: <a href=""

  8. Hi guys.
    Everything you wrote about manager libraries in kicad is true but the developers I thing had the motivation, that information for one thing must be only in one place. As we do when we design databases.
    So The initial idea was many devices must share the same footprint. The idea was good but it turned out that community found that (and it is) frustrating when designing.
    That is why in kicad V5, as libraries as concern everything is in one place like in Eagle.
    Kicad is a grate tool and do not forget it is a team work from people that having fun doing that for the community.
    KiCAD V5 will be by far best EDA package comparing even with paid EDAs. (do not forget the 3D view as well)
    But this is my opinion

Leave a Reply

Please be kind and respectful to help make the comments section excellent. (Comment Policy)

This site uses Akismet to reduce spam. Learn how your comment data is processed.