KICAD_CONFIG_HOME ... inconsistencies and detail

On KiCad 5 this environment variable controls the place used by KiCad to read kicad_common configuration file. So far, so good.

The first strange thing is that KiCad has a configuration section to store environment redefinitions. This is handy for users that lacks OS skills and wants to change the environment variables. But this creates a complex situation: a user can define KICAD_CONFIG_HOME from inside KiCad. Then KiCad will read kicad_common from the default place and all the other configuration files from what KICAD_CONFIG_HOME (the one defined inside kicad_common) indicates. Even when this behavior has some logic I find it confusing and complex. Is this a feature or a bug?

IMHO I understand that some people may need the environment configuration dialog, but allowing to define KICAD_CONFIG_HOME from this dialog creates really complex situations. Some configuration comes from one place, the rest from another.

On KiCad 5.99, I tried defining KICAD_CONFIG_HOME and it was completly ignored. Is this the intended behavior or is just a bug? I already found a bug in the current nightly reporting the config path from Python Bug 6989. It looks like the nightlies are doing some dirty path handling to redirect paths to kicadnightly instead of kicad.

I’m maintaining a script that needs to have access to KiCad configuration. It works very well on normal installations, but a user reported very bizarre things and I found what I describe. What I want to know is what should my script do.

I had a similar problem. If the KiCad installation is not using “standard paths” (whatever that means for the specific OS), then the only option is for the user to specify where their KiCad config is.

I think the KiCad devs are still trying to work out UX issues with versioned installs, and migration to new versions.

(Some of the path variables have changed just recently as told in System variables and Windows nightly installer change. Notice that the variables are for all platforms, not just Windows, although the Installer part of the announcement was naturally only for Windows.)

This is how it works:

When initializing KiCad first sets the config dir using some sane defaults. Then it reads KICAD_CONFIG_HOME from the real environment if it exists. It then overrides the default config dir with the value of KICAD_CONFIG_HOME. Only after that is the configuration opened (or new one created if it doesn’t exist yet). Path variables are read from the configuration. The original KICAD_CONFIG_HOME isn’t available in these variables, nor is it stored there.

You can define and store another KICAD_CONFIG_HOME inside KiCad but it isn’t used as the configuration location. The environment variable was read from the real environment and used once when KiCad started. Therefore it doesn’t have any effect later; the configuration location is stored inside running KiCad and isn’t changed anymore while running, not even when reading the path variables from the configuration.

I just tried setting external environment variable KICAD_CONFIG_HOME and it worked OK on Linux.

You can see how the variable is used in The settings manager has GetUserSettingsPath() and calculateUserSettingsPath(…). The latter is run once per session.

If KiCad doesn’t expose GetUserSettingsPath you can implement it in python, it’s not too complicated.

1 Like

Thanks @eelik I suggest you to try defining KICAD_CONFIG_HOME in ~/.config/kicad/kicad_common (and not in the real environment). You’ll see things are a little bit different. Always talking about stable, nightly is another history.

I tried defining KICAD_CONFIG_HOME=/tmp using KiCad’s dialog. It allowed me to do it and I got:


After this KiCad uses ~/.config/kicad/kicad_common but all the other config files are used from /tmp. I verified that it uses /tmp/sym-lib-table, /tmp/eeschema and /tmp/pcbnew.

This mix of configuration files from two different places is really confusing. If you edit /tmp/kicad_common this is ignored, and you can also have ~/.config/kicad/eeschema which will be also ignored.

I’m currently implementing in Python a lot of things, I’m asking KiCad where is the configuration, I get ~/.config/kicad/kicad_common. But then I must load this file, get the environment variables from there and then check if KICAD_CONFIG_HOME. If this is the case I must use this path for all the other config stuff. Of course I can do it, but it looks bizarre and I want to confirm this is the way to go.

If it really works that way it’s clearly a bug. At least in my opinion.

Well, it looks like, but I don’t know. This is why I’m asking in the forum instead of reporting it as a bug.

It took me a lot of discussion with the user until I realized what was going on. Is a confusing situation.

I can take a look at the source code. I may have a hunch about the problem.

Indeed the whole environment variable system in KiCad is messy and since v4->5 migration when I got familiar with it I have recommended leaving the external environment untouched (except for this KICAD_CONFIG_HOME). There’s of course an easy solution for the users: define everything inside KiCad, except for KICAD_CONFIG_HOME which must be defined only as a real environment variable.

But remember that from now on KICAD_CONFIG_HOME isn’t necessary at all to run different versions simultaneously. It’s needed only if you want to run completely separated instances of the same x.y version. It’s needed also if you want to use both v4 and v5.

The user is using it for a completly different thing. He is redirecting KiCad’s config to a directory in his “Desktop”, I guess this allows easier access from the GUI.

The config stuff was a lot messier in V5 than current master. It does sound like there is a bug here in V5, unfortunately I’m not sure fixing it will be prioritized when we are so close to V6…

What GUI? I don’t understand the use case. But it doesn’t matter much. It’s OK to use KICAD_CONFIG_HOME for any reason. However, it was never meant to be defined inside KiCad with the GUI. The sole purpose is to allow bootstrapping all the configuration from different folder, and it happens by defining the system environment variable with whatever means the OS provides.

For Windows it’s described in Step 3 in Running several KiCad versions on the same Windows machine. But if there’s no need to have several configurations for the same version it’s also possible to define the environment variable for the user with the Windows OS GUI. Then a script or shortcut isn’t necessary.

To be honest, when I wrote the instructions it never occurred to me that one could try to define KICAD_CONFIG_HOME within KiCad itself. Apparently it hasn’t occurred to anyone else either until now.

@eelik Was it not intended that way? For our team of EE designer, I’m imposing it to be set so that both sym-lib-table and fp-lib-table are automatically loaded from our library git repository, and we all share the same configuration, less surprises!

No, it was intended that you set KICAD_CONFIG_HOME in your system environment, not in the KiCad config file. Otherwise how would KiCad know where to find that config file?

I’m surprised this works at all because if you share configuration you share also all other configuration files, not just lib tables.

KiCad library system with library tables offer some flexibility but are also a bit limiting, at least with the current implementation which doesn’t allow for example per library tables or automatic or even semi-automatic updates of tables when the (official or 3rd party) libraries are changed. @craftyjon can comment on this, but maybe you could add a wish into the issue database for allowing pointing the library tables to different location than the other config. For example KICAD_FP_LIB_TABLE path variable. Or maybe this would be covered by ?

It kind of makes sense and makes it like our current usage is actually based on a bug. As soon as we are setting KICAD_CONFIG_HOME, the kicad_common file is created in that directory and pointer is updated. I thought it was nice feature to be able to set it this way honestly, as everything is centralized to KiCad.

Honestly I don’t remember seeing great documentation on this so I went with what works + simplest setup for us.

Edit: so far we had no issue with this setup and it’s only when trying out KiBot that this came up

It would be covered by 3935, but there could also be a different implementation possible without table chaining I suppose

So to be clear we do not share the kicad_common on our git, everybody sets their own path relative to our library repo. The main use of setting KICAD_CONFIG_HOME for us is to load the symbol and footprint tables automatically from this directory (and those files are shared).

BTW, Windows supports symlinks as does Linux (and Mac AFAIK). I suggest you try that if you want to share some configuration files. You have to make changes anyway when you migrate to v6 (I hope you do migrate).

Oh we will migrate for sure, I’m only waiting for the release as we can’t afford to be on the nightly builds.
Ok I guess by that time we will move to symlinks if that’s the better/recommended setup, thanks :smiley:

I don’t know if that’s better, and it’s unknown territory so I can’t recommend it. But it’s worth trying. Please tell what happens if you try.

As for the question of bugness of that behavior: at least it’s not worth fixing and I would say it shouldn’t be fixed in v5 because somebody already uses it and it doesn’t affect the intended way of using the feature.

Ok, resuming:

  • KICAD_CONFIG_HOME should be defined in the real environment, not from inside KiCad.
  • V5 allows it (unintentionally) so I must support it in KiBot.
  • It won’t be fixed in V5.
1 Like