How to create a GitHub repository compatible with KiCAD?

I’m creating a library for schematics.

When finished, I would like to put in a dedicated GitHub repository (not the official repository), to be imported by any user in KiCAD via the plugin manager.

I know I have to create some json file, so that the URL can be correctly interpreted by KiCAD.

The problem is: I have not clue whether or not exists a tool to make it, or I should write line-by-line.

In the last case: there is a syntax to follow but where can I find the documentation please?

Anything? Did I have wrong the forum?

Note: you do not need to put it on GitHub to make a library that can be distributed in the PCM, it’s just a common option.

Jon linked to the docs explaining how to create a package and add it to the official repo. If you want your own repo there is one more small bit remaining, create the repository.json and packages.json files. That process is not documented but it’s trivial if you managed to create the package itself. Just follow the example of the official repo:

Change the description and maintainer info, change the links to resources and packages file, change the update time and either remove the hash or update it to be correct hash for your files.

packages.json is even simpler, it’s just an array of package metadata.

1 Like

Thank you to both

being the first time, I just wanted to create my own repo just to get some familiarity with procedures.
Indeed to be “official” I read there are more constraint.

So per steps:

  • first trying to create my repo and in case I have problems: learn how to solve them
  • then: apply to be in the official list.

NOTE: I suppose the SHA also in the link you gave me is optional …

If your end goal is to have your package in official repo than it’s easier to just follow the steps described in official docs and also in the readme of the packages repo KiCad / KiCad Addons / Package Metadata · GitLab

One of the steps there involves testing the package you created, it will automatically generate a testing repository for you.

1 Like

Okso when I will finish the library, I think I would need a help for the rest of the things.

Ok here we are.
I downloaded everything into K:\TOOLS\metadata-main

I have Python 3.12

By applying these instructions:

The first line went good
The second line failed

So I entered into the KiCAD prompt … I gave the same command. Some step further but not so much:

where am I wrong please?

Run the first line again in the kicad prompt (only need to do it once), then the second line should work.

1 Like

oh great … it works

now … in one of the links it specifies the folder structure I must respect and make it a zip.
In the second screenshot there is the folder structure for my library
Is it correct?

NOTE: there are not footprints and not any 3D model (not necessary), thus no *.pretty nor .3dshapes


Your screenshot is not enough to get full picture but it’s not correct, symbol files should be in a directory with name symbols.

Example structure for your case should be like this:

Archive root
|- symbols
   |- my-symbols.kicad_sym
   |- my-symbols2.kicad_sym
   |- ...
|- resources
   |- icon.png
|- metadata.json

Icon is optional so you may omit resources subfolder if you don’t have one.

1 Like

ok so, I modified it. The archive root is
Inside it I have a directory called “symbols”, in which I have all the .kicad_sym

then again I created a directory called “resources” inside it I put the PNG with the logo

I stil have to create the “metadata.json”

Got it :smiley:

Now I have to finish everything (I have to draw a couple of other components) and to upload it on GitHub I think :slight_smile:

Something is not yet clear to me.

So I have validated it yes … but ti’s not sufficient.
I mean: the metadata.json should contain the package SHA, the Package size and the Install size

But at the same time that metadata.json, as far as I understood, should be inside that .ZIP … am I right? … but this alters the above mentioned data. so it will always fail the Kicad repository validation.

This is explained in the docs:

The metadata in the archive is subset of metadata for the repo.

Sorry I still don’t get it. Please be patient :slight_smile:

The file metadata.json: should or not be into the .ZIP file?
So if not: fine.
If “yes”: then the SHA etc, must be the one of the .ZIP without the .JSON inside?


This is with the JSON inside the ZIP

This is without the JSON inside


NOTE: I put on GitHub so that each time I upload a new version, the RAW address that I have to write into that JSON changes. Hence the internal JSON is different than the one I have on my machine

NOTE 2: what seems to be clear to anyone is familiar with this, it’s NOT with one that’s fully new.

You make two different versions of the JSON file.

One you put inside the zip, and in that one, you omit the download info / SHA.

The second one you put outside the zip, and that one has all of the fields.

1 Like

Ah ok fine. This indeed makes sense.

I would like also to understand why I got so many errors “package contains extra file” when I respecteds (or I think to have respected) the hierarchy

Your icon file has to be called icon.png, you can’t name it an arbitrary filename. I’m not sure why the symbols are giving validation errors, at first glance. Can you post your entire metadata file?

1 Like