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


I don’t think suggestions from Rene cam through so I will try in my own words:

You can use your own environment variables which hold the path to your own libraries. This will probably require you to change how your libraries are set up.

Anyhow using your own enviroment variables such as:
ROGER_CLARK_3D_MOD and ROGER_CLARK_MOD you can setup your own libraries and fp-lib-table entries. The fp-lib table entries should use ROGER_CLARK_MOD to point to the modules library while each module should use ROGER_CLARK_3D_MOD to point to its own 3D file.

This setup makes your module and 3D module library completely portable (for everybody who does not use the same environment variables for different purpose), so when you share the project you can share the library and person on receiving side should be able to use 3D files without any modifications (modules are already cached within the pcb file).

If you do not whish to share complete library there is always an option to write a script which scans your PCB file for 3D file references, copies the files into subfolder within the project and replace the reference such that it uses KISYSPROJ enviroment variable. (hmm this looks like a job for an Action plugin)

Only symbols libraries are somewhat difficult to share as you need absolute path. But usually it is one file only, so this not a big issue. Until v5 resolves this.


have same problem, I’ve created my own set of libs/modules and its quite convenient to keep 3dmodel in subfolder of module than mirroring whole folder structure for 3dmodels

using builtin kisys3dmod increases mess for me, creating my own globalvar (and mirroring whole structure) is quite weird

relative paths in other case works in Kicad, so why not here?


It’s still unclear to us why custom path substitution variables wouldn’t work.

Create your own variable (use Configure Paths). Add 3D shape. Use your own variable instead of KISYS3DMOD.


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.