Recommended project structure (organizing your Kicad files)

Community
1

Hi all,
How do you organize the files in your Kicad projects? I share quite a few projects that are useful to many on my GitHub as well as with customers/fabs and while the PCB and Schematic files reside in the root folder, most project will become incrediby messy if you just dump other files there as well.

A typical project om my computer is currently using the following project structure:

  • ProjectName
    • PcbName (root folder)
      • parts (schematic symbols, footprints and 3D files)
      • datasheets (for future reference)
      • schematics (PDF file for all different versions of a board)
    • Nov2024 (set of production files ordered in November 2024)
      • BOM
      • Gerber
      • Pos
      • Drawing (production drawing as PDF showing Cu, Fab, Silk & Edge layers)
    • Jan2025 (set of production files ordered in Januar 2025)
      • BOM
      • Gerber
      • Pos
      • Drawing

Something I want to implement is relative paths to Footprints/Models/Symbols stored locally and I’ll likely do that using custom variables like this as it becomes very messy having multiple versions of footprints.

I’m very curious as to how others organize their Kicad projects as I’ve not found any info such as recommendations or guidelines.

2

For local projects I’d just rename them to something like:

ProjectName-2024.11
ProjectName-2025.01

etc…
So they are actually completely separate KiCad projects.

For project in git repository (doesn’t matter if it’s a local git repo, remote github or something else) you can still use the above folders, but I’d use the advantages of git for it. You may just use commit history, but probably branches or tags are more convenient.

For example if you want to use branches - clone your Nov2024 branch to a new branch called Jan2025 and do any new changes there.
For tags - just tag a particular commit to a new tag.
You may switch between branches and tags.

3

I use Git for everything, so I would never rename anything so that file history breaks.

My question is rather: how do you organize the files needed by the project? Extra footprints, related files… Do you drop them all in the root folder? That will only work for tiny projects.

4

I don’t have anything related only to one project.
If I select element to be used I assume that I can use it also in some other project in future so I don’t have any local libraries.
My file structure I have described some time ago here:

Since than I have added also at global level a directory to collect datasheets to be linked in symbols. This directory is internally organised the same as my symbol libraries.

5

Project structure depends on how complicated a project is.

For simple project, the KiCad directory is the main directory, and I may create some sub directories for miscellaneous stuff. From documentation to some microcontroller firmware source code.

For more involved projects, I’m not so sure yet.

  • KiCad PCB.
  • 3D models for the PCB.
  • Mechanical CAD drawings
  • Micro controller firmware.
  • Documentation.

I tend to keep all sorts of projects separated, depending on their main ingredient. My projects mostly started with microcontrollers, and I’ve got them mostly sorted depending the microcontroller used for that project (AVR, STM32). It grew this way, but I don’t like it much. I’ve also got a directory with FreeCAD projects, which are mainly mechanical, but also has some CNC machines, which also have PCB’s and such.

Well, that’s a good thing I guess. I’m still struggling a bit with GIT myself, and tend to use a simpler (more intuitive to learn) ZIP files, and additionally every now and then copy projects to one of several backup disks.

When using GIT (or even my zip files) you have to decide on a strategy. Do you make a separate git repository for the KiCad PCB(s), or do you make a bigger repository, and also include mechanical CAD, etc. (GIT pojects can be stacked / linked (submodules?) but then it starts getting ever more complicated, and I like simple things.

For Gerber files, Most of them do not get backed up. Only Gerber files that are sent to a fab are backed up (i.e. put in GIT). KiCad can export gerber files to their own output directory, and I always make use of that function. The directory name for the gerber files which are (or (likely) will be sent to a fab, always have a date code (in ISO 8601 format), and I also put that date code as readable text on the PCB itself. These date codes are always unique. This means that if I do this for multiple different projects on a single day, I use the date code for yesterday, or last week.

Git is very good at keeping and tracking the history of a project. Production versions of checked states of a project can be tagged and always easily re-created from a git repository, so there is no reason to keep multiple sets of gerber files visible in the current working project tree. But when using git, do make sure you have backups on multiple disks, and preferably on multiple sites too. I think this can be done quite easily with a GIT GUI, or some simple scripts.

I also keep a text file with notes for each project. In git, you can (have to) enter some text as a description for each commit, but it’s one sentence, good for some reminder, but not for elaborate notes. In such a test file, the notes can be a bit more elaborate.