sk1fileswhere: Files- where to put them

Stop press: Color me confused.

This page was written months before January 2017. Since the introduction of the .pretty folders (for schematic symbols and pcb footprints) I have been struggling. What follows may or may not help you get to a good understanding! Though the page started long ago, I have updated it, to try to deal with the things that are confusing me. (If you are "an expert" and see serious flaws, and would be willing to help, maybe we could talk a bit, first by email, then, if easier, Skype?)

But if you are blind, I do have one eye….

There is some overlap between this page and my page about library management. But the issues are so important that it might pay you to read both… and make sure that…

*your understanding
*what that page says
*what this page says

… are all in sync!)


We all have our own working practices.

Not every aspect of KiCad works exactly the same on, say, an Ubuntu machice as it works on my Windows XP machine.

Happily, KiCad, being open source and multi-platform, is quite "well behaved" and "modest". You get to decide, mostly, where to put things! (Microsoft take note.)

While you can do "whatever you like", I would strongly recommend that you do everything you can to leave the original KiCad installation on your machine, including the libraries of components and footprints supplied with it unchanged. (You can "set" KiCad to USE only a subset of the libraries, but leave them on your hard drive so that they are available later, if you find you do need them. (eeSchema: Preferences/ Component Libraries. ("Component" being the old name for schematic symbols). PcbNew: Preferences/ Footprint Libraries)

Alongside that recommendation, I would suggest that you put "your stuff", and third party stuff (like my Arduino component and footprint libraries) in a place that is easy to see and easy to back up.

My initials are "tkb". (You'll see why I mention that in a moment!)

On my Windows machine, I have created a folder in "MyDocuments" called KiCad-tkb.

(I find the "My-this" and "My-that" folders that became the vogue a while back annoying. And have been using "-tkb" to help me distinguish the folders that were really set up by me, for me, from the ones Microsoft and other badged as "mine". Yes… I do realize that they can say they meant "folders for you to mess with". I still find their use of "My" unhelpful. Rant ends.)

Because you may one day move to Linux, where I think spaces in file names are not allowed, I suggest that you avoid them in KiCad work. Use an underscore, like_this, if you want to have your space and eat Linux too. Not only might you move to Linux, but you might want to share some work with a Linux user. You might as well start getting used to no spaces in file names.

If you want to delve into the heart of things, kicad-pcb.og offers a well set out page about the files KiCad uses, and the format of their contents. That page is probably more authoritative and up- to- date… but maybe the page you are reading can help, too. I hope so!

Within KiCad-tkb

Within the KiCad-tkb folder… which could be anywhere… I have a folder called Prjts, for "projects". (You can get into trouble if the whole path name gets too long, and we're not done yet!)

Within THAT, each time I start a project, I create a folder for it. Usually I name the folder something like "PCB042", as I have an index of my different PCB projects, with various details in it, and each project gets a number assigned to it, so I can keep them all straight. If I was doing 5 PCBs, they could have names like "alarm system" and "audio amp". Seeing as my current index number is 245, and that there are other things in my computer, too, I think you can see the joy of the PCBxxx system?

Within, say…


… there will be many files.

(Yes, by the way, I also believe that Windows people are allowed to be sloppy about capitalizations, while Linux users have to be more disciplined. For as long as I can, I will use letter case to try to make concatenated names intelligible… but woe(?) to the Linux user who enters MyFile when it was saved as myfile… or, worse, creates one of each (I think you can do that in Linux?) but thinks there's just one. So: Windows users on the way to Linux: Start being disciplined now.)

Those files are created, maintained, accessed by KiCad. (With care, you can work with them directly, too: They are simple text files. READ them, by all means. But until you are "an expert" be very cautious about messing with them!)

I have a page for you about cloning projects by working with copies of files. But even if you don't feel the need of that, remember that you can back up your work simply by making a "BU" folder within the project's folder (or elsewhere), and copying of ALL the project's folders. (Be sure you COPY the files. It is easy to MOVE them, accidentally.) Once you've done that, should your main copy die, close everything down, make "working copies" of the backups… something has already gone wrong, hasn't it? Compromise your backups? Now? I don't think so, do you? (Billy). THEN double-click on the .pro file of your working copy, and you should be away!

A frill… worth the trouble…

If, within "PCB242", I use PCB242v0-0 for everything… the .pro file, the .sch file, the .net file, the .cmp file, the .brd file… then "PCB242v0-0 will appear on drawings, which I can choose to interpret as "Version 0.0 of PCB242".

When "things" require moving on to a new version ID, it is a little tedious, but not terrible, to….

  • Create a newfolder called v0-0
  • Copy all of the project's files there
  • Rename all of the files in the main folder, changing the v0-0 to v0-1, or whatever.

(You don't actually have to copy/ preserve/ manage all of the files… but for now, just do them all and be safe rather than sorry.)

(Jan 2017: This mostly worked for me, most of the time… but some annoying glitches popped up. I was doing other things at the time, too, though, so maybe they were to blame? Takeaway: Be careful when doing these things! Moving to a "fresh start", a new version, from time to time, and preserving your earlier, "nearly good enough" answers in aspic is well worth doing, in general. Sometimes when you go to "improve" something, it all goes horribly wrong. On that day, you'll be glad that you preserved the starting point of the "improvement" process.)

The interaction between the various KiCad modules is moderated through what is in the various files. The system is no more complicated than it needs to be… but KiCad is a pretty sophisticated package… there is bound to be some complexity in the system. The Good News is that there are no proprietary files, no hidden files, no files off in some obscure corner of the machine.

eeSchema creates the .sch file, with most of the details of the schematic in it.

Running CvPcb creates a .cmp file is used. Be sure to do this before you create the netlist, if any of the devices in the project have changed, or if there are new devices since you last ran CvPcb.

Then, within eeShema, you invoke "create netlist", which creates the .net file. The "create netlist" process pulls information from the schematic and from what CvPcb created, assembling all the information PcbNew needs to put the right things, with the right rats' nest connections onto "the page". (You then arrange them, and provide tracks to make copper connections where called for by the rats' nest connections.)

Those are just examples. Throughout the KiCad design process, files are being created, read, updated, etc. The best route to mastering KiCad lies in fully understanding those data flows… but it isn't the easiest (or only!) route. You can just read these tutorials!


When you installed KiCad, the wizard installed some .lib files, and some .mod files.

In the only lapse of good planning I have noticed, an unfortunate road to confusion was created by some terminology which was adopted.

The .lib files hold libraries of schematic symbols
The .mod files hold libraries of footprints

Note, therefor: a "library" may be a .lib file, holding a library of schematic symbols, or it may be a library of footprints.

(Footprints are also sometimes referred to as modules, hence the file extension. I haven't discovered any distinction between footprints and modules.)

(If you see a reference to a "component" somewhere, it probably refers to what we now (mostly!) call schematic symbols. "Component" was a bit ambiguous.)

The "basic" schematic symbols and footprints which we used in the introductory exercise came from the "built in"/ "installed with KiCad" .lib and .mod files.

The day will come… quite early, probably, when you want to create your own schematic symbol or footprint. (That link will take you to full tutorials. For an abbreviated discussion you can visit the "skills" note on library management. )

I would suggest that you create a folder within your equivalent of "KiCad-tkb" called "Libs". you can add your initials or not, as you see fit… but the parent folder already suggests that these are things by you.

One folder for both sorts of library.

Within that…

One .lib file can hold many components. And you can have more than one .lib files.

Somewhere before version 4-0-4 of KiCad, the management of the files defining footprints changed. "In the old days", footprints were held in .mod files. ("Module" was an old name for what we now call footprints.) One .mod file used to be able to hold many footprints. And you can still read those old .mod files.

The new system is as follows… I think. (I've been stuggling a bit to get this right!)…

Somewhere… I think it can be anywhere… you have one or more folders with names like…

  • switches.pretty
  • tkb_footprints_jan17.pretty
  • foobar.pretty

… and within each of them you have one or more .kicad_mod files. (Usually more than one in a given folder.) (And yes, the "." in the folder name is just part of the folder name.)

Each .kicad_mod file defines one footprint.

Having the files on your hard disk is all the "installing" that is needed. You will, and I'll cover it elsewhere, have to tell each project to use any of these libraries that you want it to use. (And there's a way to include them in a project by default, but beware having ALL of the schematic symbols or footprints you have ever used "on tap" for every project.)

Third party libraries

At this point you shouldn't have trouble with the idea that using other peoples' .lib and .mod_kicad (or .mod) files is easy.

I would suggest a third folder in your equivalent of "KiCad-tkb". I'd call it "Lib3rdP" (LIBraries of schematic symbols and footprints from 3 RD Party sources).

You won't even have to create the files! Just copy them from the internet into the folder you set up for them, and use them! (As with your own .libs and .mods, you have to tell a project to use any of these. Not hard. Both eeSchema and PcbNew have menu entries "Preferences/ Libraries" for this.)

Third party OR your own…

One little thing concerns me. There is an answer, but I've not entirely got to the bottom of it. It is a complicated matter, unavoidably, and the KiCad answer is clever and satisfactory, but also complicated… also necessarily. I have faith that it is a GOOD answer, and it is only my failure to use the system the way it was meant to be used that is causing me the problems I have.

What happens if….

In January, I make a footprint for, say, a "model 41-231" switch, from Cherry, to use it in project PCB245. Let's say I call the footprint "swCherry41-231". I then finish that project.

In February, I start PCB246, and incorporate the same footprint in the new project, but, older and wiser, "tweak" the footprint. Perhaps the holes specified were a little too small. For PCB245 I just drilled them out, didn't I? I'm not going to reopen the footprint designer, and then redo everything "downstream" of that, am I?

But before I use that footprint in PCB246, I re-design it, with the better hole size.

Given that scenario, what happens if I then go back, and reopen PCB245, and make changes there? Will the new hole size come through automatically? Can I stay with the "old" hole size? Etc. You see the dilemma, I hope?

I'm pretty sure that the hole size, by default, in the re-opened PCB245 would be the OLD hole size. But that I CAN "update" the design to the "new" swCherry41-231 easily, too. (I think the magic is in the settings you use when reading the netlist into PcbNew).

I'm just not too clear on getting what I want by design, rather than by luck. Nor am I sure what I will get.

But, as I said, I am convinced that "the system" does know about the issues, and has answers.

The system seems to be designed to keep things as they were by default. Not only will old designs open in their old states, but if you've tweaked something, say made a hole bigger, the "fundamental" footprint isn't altered for all designs, all times… unless you take steps to make that happen in the cases where that is what you want.

Not a deal breaker… but could be important in some circumstances.

A related issue… In the above, I proposed that I'd created a footprint called "swCherry41-231". What if there is another footprint of that name in a different .pretty folder. While that name is unlikely to arise twice, the system must be able to cope with times when names do get duplicated. It must happen. Mr Murphy wouldn't miss a chance like that.

Again, I can't tell you the details of which footprint gets used… but I know there must be rules.

The good news is that CvPcb tells you what folder a given footprint has come from.

I suspect that the order of the entries in the "PCB Library Tables" dialog, reached via menu entry Preferences/ Libraries under CvPcb and PcbNew determines the default. or maybe the source library is always "attached" to any footprint, right from when you assigned the footprint to the device in the first place.

AND… connected to all of the above… I know that the system maintains at least one cache. If a schematic symbol or footprint is "missing"… perhaps you moved the project to a different computer, with different library resources?… the project will still work fine, using the cache version of the component. (But that is a two edged sword… in the case when the schematic symbol or footprint definition in the library has been changed since the project cached the old definition…. hence my uncertaintly that I am fully on top of these issues!)

So there you have it!

Before you start with KiCad, I suggest you establish those directories. As you proceed from beginners' skills to more advanced skills, you will have the good places to put things. "A place for everything, and everything in its place".

(If you are feeling kind, and can put in words how to make this page better, please write, citing "Page sk1fileswhere")

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License