KiCad 5.0 should I upgrade from 4.07?

Hi guys
This thread will probably bore you a but I needed to ask. I am a 5y+ KiCad user with a several hobby and professional project completed with KiCad.
I have a previous project that needs new rev update. It is a 100mmx50mm automation PCB with GPS, BT, GSM and 12 inputs outputs about 150 parts. I need to update just a power supply part on it and I can do that in KiCad 4 in under a day.
At the same time I am preparing to develop new project with STM32 and I would really like to start that one from scratch in KiCad 5.0. We exclusively use Linux Mint 18 and I have installed KiCad 4 with our footprint libraries. We use Git for version control for both code and KiCad projects. For new project I would like to use existing libraries as much as I can.
My questions are:

  • Given the complexity of the library system should I install the 5.0 and upgrade my old project? What are your experiences in upgrading existing projects? Will my under-a-day-upgrade become week long struggle with the libraries and broken symbols?
  • I’ve seen a diagram of how to upgrade on Windows machine, has someone come up with that for Linux?
  • Can I have two parallel installations (v4 and v5) without using virtual machines?
  • How hard it is to import single footprint from v4 to v5?
    I’ve searched the forum and found bits and pieces of information but none summed up in the same place. I’d like to hear experiences of other people after the upgrade.


I recently upgraded, following the flow chart for parrellel installation on windows with 4.0.7 and all my libraries where preserved, and upgrading existing projects was pain free, everything that I made was rescued.

This is more based on OpenGL than the legacy canvas you may have been using, so plan a half hour to get back in the rythm for selecting. e.g. the selection tool no longer asks what you want to select.

V5 can read v4 footprint libs normally. The other way round is not always possible.

Yes. But as with windows it is a bit tricky. For one you can not use the default linux mint package for achieving this. So either compile kicad your self or find a standalone package that allows you to select a different installation directory.
You will also need to work with environment variables. (The reason we so often suggest virtual machines is that it is the easy save way where you do not need to have any deep knowledge of kicad or your operating system.)

In general upgrading is easy. If you use exclusively personal libs you only need to add your libs to the library tables and you are done.
Remapping schematics (transferring them over to v5) is quite fast and easy to do as long as you have a valid cache lib in the project. I would still suggest keeping a backup around.

There is even a handy tool that allows you to exchange symbols if you want to transfer the schematic over to using the newer symbols. (tools -> edit symbol library references)

If you heavily used the official symbol lib then you will need to be prepared that we changed the organization of it.
This results in minor problems for managing old projects. If you do not care that the old project might have a so called rescue lib that holds their symbols (instead of pointing to a library in your setup) then you should be ready to go with the default library setup.
(After you fixed it up with the help of this FAQ article: I had KiCad 4 installed previosly. Now i updated to v5. Now i have some problems with the library setup)

Otherwise you would need to find a way to have the old libs available to your setup. (Or keep on using v4 for old projects)


Thanks Rene for fast reply
I tend to avoid virtual machines if I can. I have a few for different firmware development setups with commercial compilers so I can develop on a same setup in the office and at home and not be afraid that the upgrade will break something. It is OK but i prefer not to have one more VM.
We have our own library except for some simpler components like 0603 resistors and MLCCs.
I have only one project in KiCad that will need to be maintained in foreseeable future so I was hoping to upgrade that one to v5 and enjoy having everything in same version.

I do not mind having the rescue lib. I was just afraid that this will not upgrade smoothly.
My projects dir looks like below. Can I still keep the current libraries and fooprints directories with v4 footprints just in case i need to pull some old footprint or symbol that I have previously developed? I would then have under local dirs subdir v4 and v5? Sorry if I sound confused. My question is can I use v4 libraries in v5. Are they different at all. I am reading release notes on this link and I see that the libraries are different but I cannot find note on are they easy to import?
Finally, do I have to uninstall v4 before installing v5?

  • kicad/
    • libraries/
      • local/
      • external/
    • footprints/
      • local/
      • external/
    • projects/
      • project1/
      • project2/
    • third_party_libraries
      • third-party-kicad1
      • third-party-kicad2

Yes. V5 can read all library files made by v4. As i said above, the other way round is not always possible.
However if you change something in the library using v5 then it can happen that v4 can no longer read it. (V5 has more features.)

With different we do not mean that the file format changed. We mean that we reorganized the library. (So symbols got moved to differently named libs)

You can happily use your personal libs you created in version 4 after updating.
You could even use the old official lib after updating (all is explained in the link i wanted to post above. Seems i added the wrong link so here the correct one: I had KiCad 4 installed previosly. Now i updated to v5. Now i have some problems with the library setup)

Yeah I was a bit confused with the link. I get it now. I will uninstall v4 and install v5, install official libraries and then import my old libraries as I go along.
I will make an effort and backup complete kicad dir just to be on the safe side and will not update my laptop I’ll first update on my desktop machine in the office. If that goes trough fine then I will update all machines one by one.
Thanks guys for the effort. Kicad is getting better and better. I enjoy using it and I am saying that as a ex Proteus and Eagle user…

Please let us know how your upgrade to 5 went. I’m rather new to Kicad and I’m nearly finished with the development my first PCB using 4.0.7. I had to create quite a few of custom symbols & footprints and don’t want to lose all that. 3d rendering for me is a low priority.

If there ARE newer symbols & footprints available standard in 5.0 that fit my needs, I would prefer to use them rather than my custom hacks, but not at the expense of a major setback to what I’ve done so far. PCB routing for me was the most challenging and I’ve got it just where I want it. Yes, I used the Java autorouter, but the results always left quite a bit to be desired. (Sorry, I was spoiled on using professional tools, but I’m now retired.)

Will certainly do. I have few minor hardware tests to carry out before I spin the next rev. If all goes smoothly I will upgrade my machine to v5 in a few days and will get back here to share results. I will also then review standard libraries for the footprints that I use and will maybe replace them with the standard library FPs. I am always afraid of using other people’s FPs.

V5 can read V4 libraries no problem. The biggest hurdle to upgrading to V5 is the supplied libraries have been reorganized so any pointers to where a symbol or footprint in V4 is likely to be different in V5. Coupled with the upgrade process doesn’t touch your user settings, most of the problems are with old library settings pointing to libraries that have been renamed due to the reorganization. It isn’t so bad on the PCB (except for pointing to the 3D objects, but you have stated that isn’t a priority for you) because all the footprints that are being used are embedded in the pcb file. But the schematic is another story.

In your case, it is up to you if you can afford to spend the time to upgrade and fix any issues in your project now, or wait until after you have ordered the boards. Then upgrade and fix any issues in preparation for any changes you need to make to the boards. Since you say you only have one project, the upgrade process won’t be as bad as someone with, say, 100 projects. But only you know your deadlines. Just remember to make a backup of your project so you have a square one to return to if you accidentally screw the pooch.

A sensible (at least to me) process to upgrade seems to be: (I’m including information on updating the pointers to 3D objects simply for completeness. If you really don’t care about 3D models and rendering, feel free to ignore those steps.)

  1. Use the filesystem to make backup copies of your personal libraries (symbols, footprints, and 3D objects) just to be on the safe side.
  2. Before uninstalling V4 open KiCad to the project manager.
    1. Select “Configure Paths…” in the Preferences menu.
    2. If there are any of the paths greyed out, you have some KiCad system environment variables, the current thinking for V5 is that this is a bad idea. Take note of the names of the ones that are greyed out.
    3. Shut down KiCad.
    4. Delete any environment variables that you took note of above from your system. (This is just in case the V4 uninstaller doesn’t delete them for what ever reason.)
  3. Uninstall V4. This won’t touch your settings folder, but will remove any legacy libraries that are in the install location.
  4. Verify via the filesystem that your personal libraries are still around. If they got wiped out (only if they were in the same location as the standard libraries… Bad practice), make sure you put them somewhere in your system user data directory tree.
  5. Find where your global fp-lib-table is stored (it is different depending on your OS, see Rene’s link above). Either delete it or rename it.
  6. Install V5, using the default settings.
  7. Create a new project first. This can either be your next project, or a dummy project that you will later delete. This is the biggie, you don’t want to open and start remapping a current project until you have the library setup ironed out.
    1. Select “Configure Paths…” in the Preferences menu.
    2. Add the paths to where your libraries are stored. (I use three variables, one to where my symbols are, one to where my footprints are, and one to where my 3D objects are. You might be able to get away with 1 variable, but that would be too cluttered for me. YMMV)
    3. Open Eeschema.
      1. Open the new schematic library table editor. (“Manage Symbols Libraries…” under the Preferences menu.)
      2. Add your personal symbol libraries to the global libraries list. (Take note for future reference that there are two tabs, one for global and the other for project specific, or local symbols.)
      3. Note, when adding libraries, you can multi-select in the requester to load several at once.
    4. Close Eeschema and open PCBNew.
      1. Open the pcb library table editor. (“Manage Footprint Libraries…” under the Preferences menu.
      2. Add your personal footprint libraries to the global libraries list. (Take note for future reference that there are two tabs. One for global and the other for project specific, or local symbols.)
      3. Note, when adding libraries, you can multi-select in the requester to load several at once.
    5. Close PCBNew and KiCad.
  8. Optional: I like to have my personal libraries at the top of the table. I don’t know if this matters during the schematic remap or not, but I like to see my libraries at the top of the list. Because there are so many standard libraries in the tables, I find this works better in a text editor instead of clicking the “Move up” button many times in the library table editors.
    1. Find the sym-lib-table file in your settings.
    2. Open it in your favorite text editor.
    3. Cut and paste the lines for your symbols from the bottom of the list to the top of the list.
    4. Wash, rinse, and repeat for the fp-lib-table.
  9. If you have any footprints defined in your personal symbols you should check to make sure the new footprint pointer is still valid.
  10. If you have any 3D objects defined in your personal footprints, you should check to make sure the new 3D symbol pointer is still valid.
  11. Now you should be able to open your project(s) and remap the schematic (you should be prompted to remap when you first open your schematic).
    1. Fix any “broken” symbols (either the wrong symbol remapped or the symbol replaced with a box with two question marks). The new “Edit Symbol Library References…” table in the Tools menu should really help here. Double clicking a cell in the “New Library Reference” column will open the library browser to allow you to choose a new symbol if needed.
    2. Double check the footprint assignments are correct either with Cvpcb or the new “Edit Symbol Fields…” table in the Tools menu. Cvpcb might be easier to find the footprint you need and to identify the ones that have moved or changed names, but the table might be easier to change several components at once. For example, if you have 50 bypass caps that need their footprint updated:
      1. Change one in Cvpcb to use the footprint browsing tools in cvpcb to find the right footprint.
      2. Then use the table from the Eeschema Tools menu to cut and paste that changed one to the group of the other 49. As always, YMMV.
  12. Update the footprints in on your board to align with the new library organization to remove any potentially confusing legacy issues in future board revisions:
    1. Update the netlist in PcbNew one of two ways:
      1. The traditional method, generate netlist in Eeschema then load it into PcbNew.
      2. The new single step method, using the “Update PCB from Schematic…” tool in the PcbNew Tools menu.
    2. Use the “Update Footprints from Library…” tool. This will make sure the footprints in the board are the latest version in the library.
    3. Rotate and/or move any footprints that may have changed back to your desired position and orientation. (One of the many things done to the new V5 footprint libraries is their anchor point and initial rotational orientation were normalized to industry standards.)
    4. Run a DRC and correct any errors. Pad sizes may have changed affecting clearances, pad locations may have subtly changed breaking connections to traces.
    5. Labels (both Ref’d and value) may have moved and/or changed size, so check your silkscreen and fabrication layers and clean up as needed.
    6. You may need to change 3D objects and/or find new ones. Reference the 3D viewer to easily locate the incorrect (for your project) ones and/or the missing ones. (For example, the old terminal block 3D objects were low quality and none of the volunteer librarians have had the time to replace them with new high quality ones. Thus any terminal blocks won’t have 3D objects. You’ll have to find your own for the time being.)
  13. Wash, rinse, repeat for any other project. Either now or as updates are required.
  14. Your project(s) should (hopefully) now be normalized to the new libraries.
  15. Clean up any library table, libraries, and project backups as you feel necessary.

@Rene_Poschl Feel free to use my process above in a FAQ if you think it would be valuable for others. Also, if you do, feel free to make any corrections and/or clarifiactions as needed.


I forget the reasons why, but at the time I did the up-rev it seemed to be a good idea to make these changes from within the Symbol and Footprint editors. Maybe I just did not think to create a blank project.

Well, until the sym-lib-table edior tool is available to the project window, the only way to update the symbol libraries is to open Eeschema. And if you open a legacy project with Eeshema before fixing the tables the remap process will potentially be borked. Using a new project to fix the symbol libraries first should hopefully avoid much pain.

This is good advice. I’ll make sure I follow that. Didn’t cross my mind at all. I’ll make sure I backup all before…

1 Like

The library manager is available form the symbol editor. No need to open eeschema.
The symbol editor does not touch any of your project files so no danger here. (This is what @Sprig wanted to inform you about.)

1 Like

Ah. I had forgotten about accessing it from the symbol editor, since my usual workflow is to access the library editors and general project settings from Eeshema and PCBNew.

Yet another way to skin the cat. Though using a blank project helps protect fumble fingers like mine from clicking the wrong toolbar button in the project window…

My migration to V5 was long enough ago, using the nightlies, that I can’t remember exactly what my concerns were, but the process was not well documented at that point in time.

Thank you SembazuruCDE! Your instructions were very clear and well organized. My conversion to V5 went far smoother than I expected with all my normal V4 symbols and footprints being replaced with the equivalent V5 parts and all the custom ones being used from my personal libraries. The results were, my schematic and PCB layouts appeared identical to the way I left them in V4. Couldn’t be happier.

For fun, I took a look at my board with the 3D viewer and found it was not showing anything except the PCB itself. I thought that odd, since in V4 I could see more than half of my V4 components in 3D. Looking at the components, I saw the 3D maps were pointing to valid WRL files, but just not showing up. By selecting the equivalent STEP file, the 3D views were restored. Not sure what the difference was, but like I said, 3D rendering is not a high priority for me.

1 Like

Thank you for your kind words and your feedback testing my procedure. I spent several hours carefully thinking through and modifying what I though at first would be just a couple of steps… I hadn’t actually walked myself through with a live exercise of converting. So, again, thank you for being my guinea pig. :wink:

Check to make sure your 3D viewer is actually being told to render objects. Under “Display Options” in the 3D viewer Preferences menu:

One thing about the 3D model settings, and why in the supplied 3D objects you see both a .wrl and a .step for each filename. The .wrl can create a pretty rendering with colors similar to real life (if designed properly), but because it is a mesh format it doesn’t work well for integration into MCAD workflows. (Aligning holes in housing to components on the board.) The .step files work really well for MCAD workflows, but doesn’t really support colors, so will render as a matte gray object.

If you decide to use 3D objects, the suggested method is to have both a pretty .wrl and a CAD accurate .step, both with the same filename. Have the 3D object pointer in the footprint definition pointing to the .wrl for pretty pictures in the 3D viewer. The STEP output will automatically replace the .wrl extension with .step when collecting objects for output.

@maui’s StepUp plugin (for FreeCAD) is also expecting this configuration both for import (to FreeCAD) and export (from FreeCAD). Read here about it:

I’m no expert in StepUp, nor in FreeCAD, but I have successfully created a .wrl with close to real colors from a manufacturer’s .step file. I don’t know if I did it correctly, but it involved tediously selecting faces and assigning colors. Then mapping the assigned colors to StepUp’s suggestions for textures when exporting from FreeCAD to KiCad.

Check the file path very closely. We renamed most of the 3d models so assigning the step file probably fixed the file path for you. (you could probably also re assign the wrl file using the same method as you used for assigning the step file and you will get the same result.)

If you want your old projects to still render the 3d models then you would need to have the version 4 3d model library installed in parallel to the version 5 lib.

Hi all,
I upgraded a few weeks ago to 5.0 stable from 4.0.7 (under a Win10 x64 virtual machine) and had the small issues described in this post.
After getting help from @Rene and @pedro i ended up in a clean install of KiCad 5. Since i am relatively new to KiCad i didnt have many projects yet so I preferred to edit them to use 5.0 libraries (to do so, i deleted the cache library inside each project and corrected the “unknown symbol” markers in the schematics, then i repeated the CvPcb process, re-generated the netlist and voila i had my PCB updated seamlessly (almost no re-routing required! Wow!).
After being able again to generate Gerber files for my PCB maker i had a look at the 3d rendering and found that a good number of components (mainly connectors) was not shown.
I could not figure why, since i used mainly the default libraries (and i know that my 3rd party libraries do not include 3d models, grrrr…). I wonder if it is because of wrong scaling of the part or if i missed a name mismatch between footprint and 3d model.
I hope that helps

Do not do that! It might break your project. Use the normal remapping procedure. (It might result in a newly created library called project_name-rescue. But this is not a problem. It is how it is intended to work.)

If you then want to point your symbols to a new library you can use “tools -> Edit symbol library references”