Is it possible to have a 3D model, relative path to custom footprint?


because when you move it between directories eg. you change idea where it belongs
or you share link with sb, then you need additionally inform about global paths and update them in txt files (beacuse GUI sucks in most cases;/)

its not critical, after one hour with kicad you know about globalvars;] but it is really so complicated? and everyone use solution which prefer

btw I get rid with default libs/modules filtered them and make my own set of libs/modules and use one custom global var for all of it, and point all relative to it, its best for me that i invent

btw2 from what veriosn is screen which you upload?


pre-5. I didn’t remember to check if everything is available in v4. It seems that Configure Paths isn’t in v4, it must be done elsewhere.


What do you mean by “move it between directories”? Could you share a detailed use case with locations of relevant directories and files and environment variables?


If i read the suggestions here correctly i think some people would like to have a file structure like this:

Currently the structure would need to look like this


I don’t understand how that changes the situation. The suggested structure would require in fp-lib-table:

In a footprint the 3Dmodel would be

So what’s the problem? KISYSMOD must already be changed if the whole folder structure is moved to another place or you share a link or something like that.

Or did I still miss something?


Well, I tried to reread the posts again. Maybe I now understand better. The original problem was probably that if a pretty folder is added to the fp-lib-table as absolute path without path substitution variables, then there would be no need to define extra personal variable. But the 3d models would still require a variable because there’s no way to bind the location of the 3d model to the location of the footprint.


But the 3d models would still require a variable because there’s no way to bind the location of the 3d model to the location of the footprint.

And now you’ve reached the actual issue: there should be a “way to bind the location of the 3d model to the location of the footprint”. For example, by having the 3d model in a relative path from the footprint.

If the footprint is something quite unique, then the likelyhood that the 3d model will be used for anything else is quite low. Also, such “quite unique” footprints are likely to be quite a lot more complex, and are thus prime candidates for being downloaded from somewhere else.

The average user will not want to mess with custom environment variables for every single “downloaded from elsewhere” footprint/3dmodel combo, or to have to separate the download to it’s constituent parts. We want to download, add to project specific library and start using it.

Supporting relative (from footprint) AND absolute paths would enable this, without losing the ability to still have “downloaded from elsewhere” footprints, that use stuff from the 3d shapes library from KiCAD)


From my limited knowledge of KiCad internals this would be difficult to achieve.

As a footprint is put into the layout, the footprint is copied to the .kicad_pcb file. This is done so that a project can be opened even if there are no footprint libraries present. The footprint within .kicad_pcb only contains a reference to the library nickname where it came from. But it contains a full path to the 3D model (preferably using enviroment variables).

Now if 3D model would be referenced relative to footprint, then when placing a footprint into layout 3D model would have to be copied to the same relative path with respect to the layout file. This would increase project size significantly. And corner cases would be a pain to handle (e.g. 3D model relative path …/…/…/path/to/some/dir, while correct when looking from location of footprint within the library might not resolve from location of the layout). On the other hand it would decouple 3D models used in project from the library as we now have the same issue as we had with symbols in V4 but there is no cache and/or rescue tool. This is achievable with my action plugin, but it does not solve library layout.

As for the library layout, I prefer the current one. Even though I am not a library maintainer I think the current library layout (three separate libraries) make it much easier to manage the libraries. Furthermore having 3D models in separate library makes it possible to address library size issue, as some users do not care for 3D models, making their libraries quite small.

So while your wish (proposal or whatever you want to call it) is good and I understand where is it coming from, implementing it is not a trivial task by far. For the time being the best thing that you can to is follow @eelik proposal and keep the KISYSMOD and KISYS3DMOD.


I sort of get around this by just putting my special case 3d models into the project directory and then assigning the 3d model path to start with KIPRJMOD. This is demonstrated in the project I uploaded here. Granted, in that example I rather inelegantly have the one model in the root of the project, but the concept is there. This does, however, make reuse of the model clunky as every project that uses this model would need to have it copied to the project folder and the footprint hand edited to load that model. But, it does work.

Conversely, you could have an assigned path in KiCad specifically for downloaded models. This is probably the best way for now for library maintenance. Unfortunately there is no agreed upon “standard” naming convention for user libraries so portability is hampered. For example, I use KIUSRMOD and KIUSR3DMOD for my own footprint and 3d model libraries. But I recognize that the chances of anyone else using these names is vanishingly small. There is a action plugin that will archive 3d models and other things into the project folder and adjust the files to point to the project folder, specifically to make a project portable. This plugin called archive_project can be found here and was written by @MitjaN.


It would be nice if there was a comfortable way to make 3D Model folders available to KiCAD as libraries. Preferably similar to the library management of symbols / footprints. Then it would be enough for a footprint to contain the name of the 3D Model library and the name of the 3D model. (Similar to Symbols and Footprints)

No need for absolute / relative paths.


There kind of is. Have a defined path for your user 3D Models and point a KiCad path (either environment variables or in configure paths) to it. I use KIUSR3DMOD to point to a folder where my 3D models are. Within that folder I organize it with folders. So for a Bournes potentiometer model I might have an eventual path of ${KIUSR3DMOD}/Bourns/Pots/3005p.stp for the 3005 multiturn pot model that I download from the Bourns website.


I’m interested in this option too. I guess the best way would be to have multiple directory for 3D shapes. The first files that matches the module definition should be loaded.

It’s a PITA to have /usr/share/kicad/modules/packages3d with all defaults (2.7GB of 3D shapes) and not being able to add a path in your local workspace/home or any other directory to load 3D shapes from it.

You have 2 options as for now:

  1. Get root and copy your files into the system wide path so you can keep everything Ok
  2. Define a local directory and copy /usr/share/kicad/modules/packages3d into it.



Not sure why you paste a link without writing anything but did you notice I wrote “add” and not “change”? I think you are not getting the idea where saying “multiple paths” should be great. Adding a path to KISYS3DMOD with “;” as a separator won’t work.


Yes sadly having multiple search paths does not work in kicad. There is a reason for this. What happens if your multiple search paths have the same thing in them.

The suggestion is to use a personalized path variable for your personal libs.
So instead of using KISYS3DMOD in the 3d path setting of your footprint use MY3DMOD.

If you want to add a 3d model for a footprint found in the official repo i would suggest you move all the 3d models out of the system directory and into a user accessible place. Point KISYS3DMOD to that location and be done with it. (Maybe even directly clone the repo instead of using the files that come with the installer. This gives you the option to easily update the files without needing to download everything again.)

We here can not change how kicad behaves but we can tell you how to work around the current limitations.


It is a suggestion to read the doc.
As René suggested you have to add a new environment variable to have multiple path.
In general having multiple search path is a bad habit because of the risk of duplicates, as René explained.
It is much better to organize your local lib with what you need, updating it depending on your needs.


Ok. Thanks for suggesting. I was already aware of that, and also I wrote the only two options as a workaround. Those options are what you are suggesting me so my guess was you didn’t read/understood.

My suggestion is pretty simple though: You load the very first file that matches the model needed. In fact, when you edit a component you can add a 3D shape for it. The .mod file has a model attribute where you can define a relative path pointing to the .wrl file, just like:

some .mod excerpt:

(model some/relative/path/my.wrl

If you have multiple path, Kicad could look for my.wrl in those path and load the first that matches. PATH variable in linux works that way, it could be a list of paths where you could find executables. Typing an executable file in the terminal will look for the file in PATH and load the first match.

Why this could be an issue? I think it should be a valid approach.


That is not a good solution. See the current symbol none sense! (Yes it is an easy solution that seems good on the surface for users who do not want much control but something that just works. But it really does not work for users who want exact control over what is happening.)

And as i stated above: This is a user forum, suggestions for changes need to be discussed with the devs over at the bugtracker

For me personally a better approach would be something as follows.
Introduce a layer that i call collection. A collection is a closed library of libraries holding symbols, footprints and 3d models. The collection has its own library tables (fp-lib-table and sym-lib-table) and its own 3d path variable (the later can be determined by the collection base directory and might not need a variable at all.)

Kicad then has a central library management where you can add such collections.
This however would require another file format change if you want to include the collection name in the symbol or footprint paths (to avoid naming collisions). Or it would result in having a priority system again.

I have not yet fully thought out this system but i think it might make a lot of things a lot easier for users. It would do away with the path management stuff that seems to be so hard to understand for beginners (Adding a collection can setup the base path correctly. A collection could have a fixed sub path layout)

As soon as i have it together for myself and have it written up nicely i will approach the devs with this idea.


I think it is fine for Unix PATH and people who understand the nuts and bolts of the OS, but doesn’t work well for users whose knowledge of search paths is zero. As Rene points out, the v4 method of locating symbols has caused loads of confusion.

I think retracing the steps of search paths would be very retrograde.

KiCad needs to adopt a sensible model where data packages can be easily installed into a KiCad instance, are unambiguous and easily updated. It does not need to be complicated, Arduino IDE uses a simple model which is easy to use and understand.

I prototyped such a system with kipi, but I did get a bit stuck with the 3d models. I came to the conclusion that we must also eliminate file system links in data files in order to move forward.


I think I have a similar idea, though I would them “packages” rather than “collections”, but it is really the same thing. Since we have library tables for other things, I wonder if we should have library tables for 3d models (a “library” being a folder containing files, similar to a footprint library).

I am not sure if a collection needs to have it’s own tables, if it adds a further level of naming. The approach I used to identify a collection is to use the properties field in the library tables to identify the collection name (and version etc). Then the global library tables can be used.

Clearly, collection names need to be unique, but if they are a reasonably long string it should be easy to avoid collisions by sensible cooperation. If not, it would be easy to create a git repo to register names.

But, I really think we must allow for all types of data to be included in a collection, i.e. plugin scripts, Spice models, project templates etc. We don’t need to implement them all at once, but the syntax and format should be easily extendible to new types of data.

I wrote some wiki pages on kipi,, although I didn’t complete it yet.