KiCad nightly (v5.99): New schematic and symbol library file formats are now the default

The new s-expression schematic and symbol library file formats are now the default and should be available as soon as the nightly builds are complete. All new schematics and symbol libraries will be created using the new file formats. All existing schematics will be converted to the new file format on the first load and all subsequent changes will be made to the new file format. The old schematic files remain unchanged and no further edits will be made made. It is still a good idea to make a backup of all existing schematic files just in case something goes wrong.

There are a few things to be aware of when switching between the 5.1 and development branches:

  • Please allow all library symbol rescuing and remapping to complete to ensure that the library symbols will be saved to the schematic files. If either of these steps are aborted, saving the schematic will certainly result in broken symbol links which will require manual intervention to resolve.

  • The symbol library cache is no longer required for the new file format. Converting back to the legacy file format may result in broken symbol links so avoid converting between formats. Schematics are now fully portable without the cache library.

  • Version control software users must add the new schematic files (*.kicad_sch) to ensure change control is maintained.

  • In the short term, the ability to save schematics and symbol libraries to the old file format will be maintained for testing purposes. Once new schematic and/or symbol library features are added, saving to the old file format will be deprecated to prevent data loss between format conversions.

  • The new schematic file format fixes a long standing bug when sharing schematic files between projects. Prior to the new file format, sharing files between projects in a simple hierarchical design required the symbol annotation to be maintained in the shared file(s). This limitation has been removed and the annotation can be changed in the shared file because annotations for the entire project are saved in the root schematic file. Root schematics can also be shared by other projects as well because annotations in hierarchical sheet schematic files are ignored and are not changed by the project.

If you find any issues, please be sure to file a bug report at GitLab so that it can be fixed as quickly as possible.

Thank you for your patience as we work through any issues with the new file formats. Once the existing feature set is stable, expect to see new schematic and symbol library features added fairly quickly.

KiCad Development Team


Is there canonical documentation for these new file formats someplace?


(EDIT: this is no longer the case; see the post #30 below.)

This seems to be crucial, yet easily lost when reading the instructions. #4324 was the first bug report probably caused by the migration.

So, if updating the PCB from schematic seems to have problems after changing to the new file format, this must be used first:


1 Like

The new schematic file and symbol library file formats are documented. At some point, these documents will be converted into formal documentation and added to the developer documentation. You really shouldn’t need documentation. One of the goals of all KiCad file formats is human readability so if you cannot understand reading a file without documentation, then we have failed on that front.

This helps when one wants to read a file but does not really help if one writes a script that parses one. Because one really does not want to make a file in the hopes that every possible feature of the file format is in it.

The new formats are in, but not frozen, so anyone who wants to write scripts against them should be aware that they are still a moving target until V6 feature freeze.

Well we librarians will need some time to get our scripts back up running. So you will need to have a format freeze long before the release.

@Rene_Poschl I don’t expect much if anything in the way of changes for the existing feature set. Obviously that will change once we begin adding new features. I suspect once the Python schematic API is implemented, it will make more sense to use that to generate symbol libraries.

Its not about generating. We need to parse the libs in python for our continuous integration scripts. (I hope we can reuse the rule checking part and only need to exchange the parser but am not sure if the script is really build to make this easy)

It is probably safe to start on that work. The parser portion should stay constant, it’s just a question of whether some fields will be added.

Will the new format replace the libs on or are you going to support both at once forever?

The official libs will be converted to the new file format. Right now we start to experiment with conversions and will report any problems we find with the process. We will additionally check if our rule set needs to be updated (i expect it will need to change).

As soon as we are happy we will stop v5 development (except fixing of major bugs) and focus on getting the lib ready for v6.


Will the new format libraries be getting new names?
Keep the names unchanged and migration V5->V6 is less painful, but V5 users will inevitably get hold of V6 libraries

We do not plan a reorg this time around so most libs and assets will keep their current name. Some libs are currently a mess and will hopefully get a major rework (if we have time for it).

So two sets of libraries on GitLab in parallel with the same names. The V6 version is going to need to be started almost a year before V6 goes to official release as there is so much to be done

1 Like

Can this step be made automatic? “You must update the board from the schematic using references before making any changes to the schematic” ?

Because otherwise, it seems to delete and replace every part using the forward annotation.

I can see it being quite error-prone. I’ve so far only tried it on a junk “test” project.

AFAIK, there is no way to force the PCB update dialog settings (see dialog image above) when forward annotating so I’m not sure this solution would be significantly better as it would still depend on the user choosing the correct settings. It also depends on the status of the design. If the design is complete and the schematic and board are fully synchronized, then this makes sense. If the design is in progress and the schematic and board are not synchronized, then it is not so obvious what the correct settings should be. Any “fix” would be a trade off. There is no silver bullet solution here.

No not two sets of libraries. The master branch will be converted to v6 and v5 libs will be on their own branch such that we can still fix major bugs (but the v5 libs will then generally be frozen, we will not even fix minor bugs only critical stuff.)

1 Like

Will the library repository be mirrored to ?