KiCAD 9.0: Setting Up Your Project Environment

The first step in using KiCAD effectively isn’t drawing a schematic—it’s building a disciplined project environment. If you plan it right from the start, everything that follows (layout, manufacturing output, part libraries, even version control) becomes significantly easier and more reliable.

1. Project Structure: Blueprint for a Portable, Maintainable Workflow

A KiCAD project is more than a collection of files—it’s a living system. Whether you’re a solo designer prototyping a sensor module or a team building a multi-layer RF board, the way you structure your project will determine how easy it is to build, share, debug, and reproduce.

KiCAD’s design philosophy is folder-centric. It doesn’t hide its internals behind a monolithic container or proprietary database. Everything—from your schematics and PCB layouts to custom parts and output files—lives in the file system. This is a gift. It means your project is inherently portable and version-controllable, if (and only if) you organize it with intent.

The root of your project should be its own dedicated folder—nothing borrowed, nothing scattered. At its core are the primary design files:

• The .kicad_pro file: the project's brain, storing references and settings.

• The .kicad_sch file: your schematic, the abstract circuit-level view.

• The .kicad_pcb file: the physical board, with traces, pads, and layers.

• The .kicad_prl file: a per-user UI preferences file, often excluded from version control.

Around these files, you layer in structure. A clean, scalable project might look something like this:

my_project/
├── fp-info-cache              ← This contains footprint information
├── my_project.kicad_pro       ← Master project file
├── my_project.kicad_sch       ← Main schematic sheet
├── my_project.kicad_pcb       ← PCB layout
├── my_project.kicad_prl       ← Per-project preference file
├── symbols/                   ← Custom symbols for schematics
├── footprints/                ← Project-specific .pretty folders
├── 3dmodels/                  ← STEP/VRML models for enclosure fit
├── outputs/
│   ├── bom/                   ← Bill of materials (CSV, XML, XLSX)
│   ├── gerbers/               ← Manufacturing Gerber files
│   ├── fab_drawings/          ← PDFs of assembly drawings, layers
│   └── stencils/              ← Paste layer Gerbers or DXFs
├── templates/                 ← Optional templates for reuse
├── constraints/               ← Netclasses, clearance, stack rules
├── test/                      ← Firmware or board test scripts
└── notes/
    ├── CHANGELOG.md
    └── README.md

This structure has four goals:

1. Portability: everything important lives within one folder

2. Reproducibility: consistent library paths mean no broken symbols

3. Collaboration: others can clone the repo and start work immediately

4. Longevity: six months later, the file you need is where you expect it

Keep custom symbols, footprints, and 3D models in relative paths inside your project. Avoid relying on global paths—your teammate won’t have the same desktop.

2. Deep Dive: What Each File in KiCAD 9.0 Actually Does

KiCAD’s file system is deceptively transparent. Each component of your project lives as an independent, visible file. This modularity means you can audit changes, debug file corruption, or track specific pieces of a design over time. But it also means you need to know what each file does—what’s essential, what’s optional, and what can safely be ignored.

Let’s walk through the anatomy of a typical KiCAD 9.0 project.

The Project File (.kicad_pro)

This is the central nervous system of your project. It stores configuration data that ties everything together—UI preferences, layer visibility settings, grid size, units, color schemes, and paths to libraries. When you open your project, KiCAD reads this file first. It doesn’t store any actual circuitry or board layout data, but it defines how you see and interact with that data.

Schematic Files (.kicad_sch)

This is where your electrical intent lives. The .kicad_sch file contains the schematic—the high-level abstract representation of your circuit. It defines components, their interconnections, hierarchical sheets, and embedded field data. If your design includes hierarchical subsystems, each one gets its own .kicad_sch file. These are not just visual diagrams—they are electrical blueprints, and they drive the netlist that powers your layout.

Layout File (.kicad_pcb)

This is your physical design. The .kicad_pcb file defines copper traces, vias, pads, zones, mechanical outlines, and silkscreen layers. It’s the board as it will be manufactured—down to the micron. Once you import the schematic connectivity into the layout, this file becomes the canvas on which your design takes real-world form. Any DRC violations, copper pours, or mechanical clearances are resolved here.

Legacy Netlist File (.net)

Once essential, now mostly deprecated, the .net file is a textual export of the schematic’s connectivity. It was historically used to bridge between the schematic and PCB layout, or to drive third-party tools like SPICE simulators. In modern KiCAD workflows, it’s rarely needed unless you’re interfacing with external validation or simulation pipelines.

Symbol Libraries (.kicad_sym)

Symbols are the visual and metadata representations of electronic components at the schematic level. Each .kicad_sym file may contain one or more symbols, and these files can be stored either globally (for all projects) or locally (inside the project folder). Local storage ensures your project won’t break if you later change a global library—a key part of making your designs self-contained and version-safe.

Footprint Libraries (.pretty/.kicad_mod)

Footprints define the physical copper pattern for soldering a component onto a PCB. A footprint library in KiCAD is a folder ending in .pretty, and inside that folder are individual .kicad_mod files—each representing one footprint. Like symbols, footprints can be global or local, but for collaborative and archival use, keeping them local is safest. That way, no one on your team ends up with missing pads or mismatched pinouts.

3D Models (.step, .stp, .wrl)

These files give your board its mechanical context. You don’t need 3D models to manufacture a board, but they’re essential for enclosure fitting, thermal simulations, and client-facing renderings. STEP and STP files are widely used for CAD integration; VRML (.wrl) is used for quick visual previews. KiCAD links these models to your footprints—again, using paths that should always be relative.

Output Files (.gbr, .drl, .pdf, etc.)

Once your board is complete, KiCAD generates output files for manufacturing. Gerbers (.gbr) describe each copper and mask layer; drill files (.drl) define hole locations and sizes; PDFs are often exported for documentation, such as fab drawings or layer previews. These files live in a separate folder (usually outputs/ or export/), and they’re regenerated every time you re-export. Don’t include them in version control unless you’re archiving for regulatory or customer traceability.

Temporary and Auto-Generated Files

There’s a cloud of auxiliary files that KiCAD produces in the background—.bak for backups, .kicad_auto for autosaves, .cmp for annotation data, and others. These are not permanent and should not be archived or committed to source control. A good .gitignore takes care of these automatically.

The real design lives in your .kicad_sch and .kicad_pcb files. The project file defines the environment around them. The symbols and footprints act as dependencies. And everything else—the outputs, backups, netlists, 3D models—either supports or expresses the design without modifying its core logic.

Knowing where each piece fits not only helps you back up or version your work, it also makes you a better teammate and a safer designer. You stop guessing where things are, and you start building with confidence.

3. Libraries: How KiCAD 9.0 Finds Your Parts

In KiCAD, everything is built on libraries. Symbols define how components look and behave in your schematic. Footprints define how they land on your PCB. 3D models give them physical volume. Every resistor, capacitor, IC, and connector you place is a reference—pointing to something deeper. To work efficiently and without surprises, you need to know how KiCAD finds those references.

At the core, KiCAD distinguishes between two types of libraries: global and project-local.

Library Type	Where It’s Stored	Best Use Case
Global	Config directories in your OS	Shared, stable symbols across all projects
Project-Local	Inside your current project folder	Custom parts, modified footprints, early prototypes

Global libraries live outside any one project. When you first install KiCAD, it comes preloaded with a wide array of symbol and footprint libraries—thousands of standard parts curated by the community. These live in system-level directories defined by your operating system, often in locations like ~/.config/kicad/9.0/symbols or Program Files on Windows. They’re meant to be shared across all your projects. If you regularly use standard 0603 resistors, 74-series logic gates, or USB connectors, these libraries are perfect. They’re stable, versioned, and generally safe to rely on across projects.

But global libraries come with a catch: they’re external dependencies. If you open your project on a new machine, and that machine doesn’t have the same global libraries—or the same version—you’re in trouble. Footprints might go missing. Symbols might not render. And your schematic might break, even if your design is perfect.

That’s why KiCAD supports project-local libraries: symbol and footprint libraries that live right inside your project folder. You create them when you need custom parts, early prototypes, or modified manufacturer footprints. These libraries travel with your project. If someone clones your Git repository, they get the exact same parts, with no setup needed.

Starting with version 9.0, KiCAD defaults to using relative paths for these local libraries—and that’s a big deal. Instead of referencing a fixed, fragile path like

C:/Users/User/Documents/MyLibs/my_ic.kicad_sym

KiCAD uses environment variables. If your custom symbol is stored inside your project’s symbols/ folder, it will show up as:

${PROJECT_DIR}/symbols/my_microcontroller.kicad_sym

This makes your project portable. If you zip it and send it to a client, it still works. If your teammate clones it into a different directory structure, it still works.

Everything resolves from the root of the project, and nothing relies on your local setup.

You can define your own custom environment variables too, via

Preferences → Configure Paths

This gives you clean shorthand for frequently used directories. Maybe you store your curated corporate libraries in ~/KiCAD_Libraries. You can map that to ${MY_LIBS} and then reference parts like:

${MY_LIBS}/opamps/lt1011.kicad_sym

The same applies for 3D models. If you keep mechanical models in ./3dmodels/, define a variable like ${PROJECT_MODELS} and use it everywhere your footprints link to .step or .wrl files.

Behind the scenes, KiCAD maintains two library tables: one for symbols and one for footprints. You manage them via

Preferences → Manage Symbol Libraries

and

Preferences → Manage Footprint Libraries

Each entry in the table includes a nickname (used in the schematic or board), the file path (absolute or relative), and the scope—either global or project. When you add a part to your schematic, you’re not placing a file—you’re placing a pointer. That pointer must resolve somewhere.

If you ever open an older project and get warnings about missing libraries, this is likely why. The paths have changed, or the environment variables are undefined. The fix is usually simple: open the library manager, reassign the paths using environment variables, and save.

A well-configured library setup does three things:

1. It makes your project self-healing—able to move from system to system without breaking.

2. It protects your design from upstream library changes that could break footprints or symbols.

3. It gives you clarity. Every part in your project points somewhere that makes sense, and you can trace it all the way back to its source.

Libraries are infrastructure. Invisible when everything works, absolutely critical when things don’t. Learn how KiCAD resolves them, and you’ll never be caught off guard by a broken footprint or a vanishing capacitor again.

4. Preferences: Creating a Predictable Editing Experience

In any design tool, consistency is key. You don’t want to waste time hunting down settings every time you open a new project or switch computers. KiCAD 9.0 has two layers of preferences—global and project-specific—that let you fine-tune your experience. Understanding the distinction between them will not only make you more efficient but also help maintain design integrity, especially when working across multiple systems or within a team.

Global Preferences: A Universal Approach

Global preferences are the settings that KiCAD uses universally across all projects. These settings live in your OS-level configuration folders and define how KiCAD behaves on your system. This includes things like your user interface (UI) theme, hotkeys, recent projects list, and canvas behavior. In essence, they shape your personal working environment.

For instance, if you prefer a dark theme with specific keybindings for common tasks like zooming or switching layers, you would adjust these settings under the global preferences menu. These choices affect every project you open, giving you a seamless experience from one design to the next, no matter the specifics of the circuit you’re working on.

Additionally, if you’re someone who works on multiple computers (maybe one at home and one at the office), these global preferences become especially useful. By exporting them, you can replicate your ideal working environment across all your setups. KiCAD makes this simple with an export feature found in

Preferences → Manage Preferences → Export Preferences

This creates a small .json file containing all your UI preferences—your color themes, hotkeys, canvas zoom settings, etc. You can then import this file on another machine to ensure everything behaves exactly the same way.

Project Settings: Tailoring to Your Design Needs

Project settings, on the other hand, are tied specifically to the project you’re working on. These are saved in the .kicad_pro file, and they govern the design-level aspects of your work. Project settings include essential design parameters like netclasses, grid spacing, units, and schematic appearance. If you need to define specific design rules—such as trace widths or minimum clearances—these are stored in your .kicad_pro and .kicad_pcb files and are inherently project-specific. This makes them travel with the project when shared with collaborators or moved between systems, ensuring that the design constraints and layout rules remain consistent.

For example, let’s say you’re designing a high-speed PCB and need to follow strict trace width and clearance guidelines. These design rules would be set within the project’s settings, and anyone who opens the project will have those constraints active, reducing the chance of errors when transferring the project between systems.

How Preferences Influence Teamwork and Collaboration

In a team environment, these preferences can significantly improve collaboration and reduce potential conflicts. While global preferences keep the working experience consistent across systems, project settings ensure that everyone adheres to the same design constraints. This way, even if one person adjusts the grid spacing or changes the schematic appearance in their local environment, the core design settings remain intact and consistent for the whole team.

For example, if one team member adjusts the grid spacing for easier component placement in a specific project, that adjustment is stored within the project itself. When another team member opens the same project, it will load with the same grid settings, preserving the integrity of the design process.

Exporting and Sharing Preferences

Once you’re happy with your global preferences or project-specific settings, you can easily export them for reuse. This becomes invaluable when switching between different machines or when you need to onboard new team members. By using the export feature, you create a universal starting point for anyone working on the same project, ensuring that the design and editing experience is consistent.

To make sure the settings travel with your project, ensure that all relevant preferences (design rules, schematic setup, etc.) are set at the project level. This ensures that even if you share your files with someone else, they will open the project with the same settings.

5. Templates: Build Once, Reuse Forever

In any design environment, efficiency and consistency are paramount. In KiCAD 9.0, templates serve as a powerful way to achieve both. Think of a template as a reusable starting point for new projects. Rather than recreating the same configuration—schematic structure, layout rules, netclasses, and libraries—every time you start a new design, you can set up a template once, then effortlessly reuse it, saving hours of setup time for every new project.

Why Templates Matter

Templates are particularly useful when designing similar circuits repeatedly. Whether you’re working on a series of power supply designs, sensors, or any kind of board that follows a familiar structure, having a template that already includes your preferred settings will keep your workflow smooth and consistent. This eliminates the need to repeatedly adjust parameters like netclasses, grid size, preferred footprints, and schematic setup for every new design. It’s all baked into the template. You can even customize the template to include libraries you regularly use, specific pinouts for components, or even custom scripting to automate certain tasks.

Beyond personal efficiency, templates also play an essential role in collaborative environments. If your team uses the same starting point for every project, you ensure that designs follow the same conventions and standards from the get-go. This consistency reduces errors, improves communication, and speeds up the process when multiple designers are contributing to the same project.

How to Create a Template in KiCAD 9.0

Creating a template in KiCAD is a simple, yet highly effective process. Let’s walk through how to do it step by step.

Step 1: Set Up Your Project

Begin by creating a project in the usual way. This includes:

• Designing the schematic

• Setting up the PCB layout

• Defining your preferred netclasses (trace widths, minimum clearance, etc.)

• Adding the footprints you want to use regularly

• Specifying any other custom settings that will help streamline your design process

At this stage, treat the project as if it were a normal project that you would actively work on. You’ll configure it just the way you want future projects to start—because that’s exactly what it will be!

Step 2: Add the Template Metadata File

Now, create a meta/info.json file that will house important information about your template. This metadata is key for organizing your templates and ensuring they’re correctly identified when you want to use them in the future. Here’s an example of what the metadata file might look like:

{
  "name": "4-Layer Power Supply Template",
  "description": "Template for switching power supplies with pre-tuned netclasses and stackup",
  "author": "Team Alpha",
  "version": "1.2",
  "kicad_version": "9.0"
}

This small JSON file is where you specify:

• Name: The name of the template (e.g., "4-Layer Power Supply Template")

• Description: A short explanation of what the template is designed for (e.g., "Template for switching power supplies with pre-tuned netclasses and stackup")

• Author: Who created the template (e.g., "Team Alpha")

• Version: The version of the template

• KiCAD Version: The version of KiCAD the template was created with, ensuring compatibility with future versions of the software.

This file will go into your template folder, where KiCAD can find it later.

Step 3: Save Your Template

Once the project is ready and the metadata file is in place, it’s time to save your template in the correct folder so KiCAD can recognize it. Depending on your operating system, the template folder is located in different paths:

• Linux: ~/.local/share/kicad/templates/

• Windows: %APPDATA%\kicad\templates\

• macOS: ~/Library/Application Support/kicad/templates/

Simply move your entire project folder (the one you set up earlier, along with the meta/info.json file) into the correct templates folder for your operating system.

Step 4: Select Your Template

Once your template is saved, it’s ready to be used! To start a new project from your template, go to

File → New → New Project from Template

KiCAD will prompt you to select the template you want to use, ensuring that your next project starts exactly how you want it, with all the settings, footprints, libraries, and design rules you’ve preconfigured.

Benefits of Templates

Using templates consistently across your team or in personal projects brings many benefits:

1. Consistency: Every design starts with the same foundation, making it easier to maintain uniformity in design practices.

2. Efficiency: No more setting up every project from scratch. Once a template is created, it’s just a few clicks to begin a new project with all the right settings.

3. Faster Onboarding: New team members can use templates to ensure they follow established design practices right away, without needing to spend time configuring their environment.

4. Customization: Templates are fully customizable, meaning you can include whatever you need to streamline your process—whether it’s custom components, pre-configured outputs like Gerbers or BOMs, or specialized libraries.

6. Output Automation: Using kicad-cli

One of the most powerful new features in KiCAD 9.0 is the inclusion of kicad-cli, a command-line interface that allows you to automate many aspects of the PCB design process. This tool enables you to script various operations within your KiCAD projects, such as generating PDFs of schematics, exporting Gerbers, performing Design Rule Checks (DRC), and even managing Bill of Materials (BOM) exports. By integrating these automated tasks into your workflow, you can not only save time but also ensure repeatability and consistency, which is essential when working with teams or managing large projects.

Why Use kicad-cli?

The power of kicad-cli lies in its ability to automate repetitive tasks, integrate with Continuous Integration (CI) workflows, and ensure that your project’s output is always up-to-date and reproducible. Whether you're generating output files for manufacturing or running automated checks on your design, this tool brings significant efficiency and reliability to your workflow. Some of the most practical uses include:

• Automated BOM audits: Automatically generating and verifying your BOM to ensure parts are accounted for.

• CI/CD integration: Automating design checks, Gerber generation, and schematic exports as part of a larger pipeline.

• Nightly builds and reports: Running nightly builds that check for DRC errors or regenerate Gerbers for a batch of boards.

These are just a few examples of how the command-line interface can enhance your workflow and integrate your KiCAD projects into a broader development and manufacturing pipeline.

How to Use kicad-cli

To get started with kicad-cli, you'll first need to install the tool (it comes bundled with KiCAD 9.0). Once installed, you can begin using it to automate common tasks. Here are some examples of how to use kicad-cli effectively.

You're absolutely right—and that missing detail makes a big difference, especially if you're just getting started with command-line tools in KiCAD 9.0. Let’s fix that properly and make this whole section self-sufficient.

6. Output Automation: Using kicad-cli

KiCAD 9.0 includes a powerful command-line interface: kicad-cli. This utility lets you automate your project’s outputs—schematic PDFs, Gerber files, BOM exports, DRC reports, and more. It’s especially useful for batch processing, CI/CD workflows, or just cutting down on repetitive tasks.

But before you can automate anything, you need to know how to find and run it.

Finding & Launching kicad-cli

kicad-cli is installed alongside KiCAD 9.0, but where and how you launch it depends on your operating system.

If you’re on Windows:

1. When installing KiCAD 9.0, make sure the option to "Add KiCAD to system PATH" is enabled. If not, you can manually add it.

2. Open PowerShell or Command Prompt.

3. Type:

   kicad-cli --version

   If it prints something like kicad-cli 9.0.0, you're good to go.

If you get a "command not found" error:

• Navigate to KiCAD’s install folder (usually C:\Program Files\KiCad\9.0\bin).

• Run:

  .\kicad-cli.exe

You can also add this directory to your system’s PATH variable so that kicad-cli is always available globally.

1. Generating a Schematic PDF

One of the first steps in a project is often creating a PDF of the schematic to share with collaborators or for documentation purposes. With kicad-cli, you can generate a schematic PDF from the command line quickly and efficiently. Here’s the syntax:

kicad-cli sch export pdf my_project.kicad_sch -o outputs/fab_drawings/

• my_project.kicad_sch: This is the schematic file for your project.

• -o outputs/fab_drawings/: This specifies the output directory where the PDF will be saved.

This command will take your schematic file and convert it into a high-quality PDF, which is particularly useful for documentation or sharing with non-technical stakeholders.

2. Exporting Gerbers for Manufacturing

Gerber files are the industry standard for PCB manufacturing, and kicad-cli makes it easy to export them. The command for exporting Gerbers looks like this:

kicad-cli pcb export gerber my_project.kicad_pcb -o outputs/gerbers/

• my_project.kicad_pcb: This is the PCB layout file for your project.

• -o outputs/gerbers/: This is the output folder where your Gerber files will be placed.

This command generates all the necessary files for PCB fabrication, including copper layers, silkscreen layers, drill files, and other essential manufacturing data.

3. Running Design Rule Checks (DRC)

Design Rule Checks are crucial for ensuring that your PCB meets the required specifications, such as trace width, clearance, and other manufacturing constraints. Instead of manually running the DRC through the KiCAD interface, you can automate it with kicad-cli. Here’s how to run a DRC check and save the results:

kicad-cli pcb drc my_project.kicad_pcb --output outputs/reports/drc.txt

• my_project.kicad_pcb: This is the PCB layout file.

• --output outputs/reports/drc.txt: This specifies where the DRC report will be saved.

This command runs the DRC check on the PCB and outputs a report to a text file, which you can easily review to ensure that the design complies with all necessary rules and constraints.

Automating Workflows with kicad-cli

Beyond individual commands, the true power of kicad-cli comes when you integrate it into a larger automated workflow. Whether it's setting up a Continuous Integration (CI) pipeline using GitHub Actions, GitLab CI, or Jenkins, you can automate the entire process of design checks, BOM exports, Gerber generation, and more.

For example, you might set up a GitHub Actions workflow that runs every time you push changes to the repository. This workflow could automatically:

• Run kicad-cli to perform DRC checks.

• Generate updated Gerber files.

• Export the BOM in your preferred format (CSV, XML, etc.).

Such automation ensures that all the important output files are always up to date and that design errors are caught as soon as they occur.

7. Git Integration: Keeping the Right Files in Version Control

Version control in KiCAD isn’t just about “saving backups.” It’s about unlocking powerful workflows: team collaboration, easy reverts, commit-by-commit design tracking, and CI-driven output generation. But getting there requires one essential habit—tracking the right files, and ignoring the rest.

Think of your KiCAD project like a bonsai tree: precise, deliberate, and intolerant of digital weeds.

What Belongs in Git

At the core of your repository should be the minimum viable set of files that completely define your board’s intent—your schematic, layout, and rules.

• The project files:.kicad_pro, .kicad_sch, .kicad_pcb — these are the heart of your design.

• Custom part libraries:Any custom schematic symbols, footprints (.pretty/ directories), and 3D models (.step, .wrl) that your board depends on. These must live in your project folder or a shared submodule.

• Library tables:sym-lib-table, fp-lib-table — especially if you’re using project-local libraries or custom path variables.

• Constraints and production data:Netclass definitions, board stackups, fabrication drawings, templates, and documentation like README.md or CHANGELOG.md. If it expresses an engineering decision, it belongs in version control.

What to Keep Out

KiCAD generates a lot of transient fluff—autosaves, backups, throwaway exports. Tracking these will clutter your diffs and poison your commit history.

Skip these:

• .bak, .kicad_auto, .cmp — ephemeral backups that KiCAD manages on its own

• .net — legacy netlists not used in modern KiCAD workflows

• Output files — PDFs, Gerbers, BOMs — unless you explicitly want to freeze and archive them for releases or manufacturing

• Logs, temporary reports, and autogenerated scripts

Here’s a solid starting point for your .gitignore:

*~
*.bak
*.kicad_auto
*.cmp
*.net
__pycache__/
outputs/
notes/*.log

If your outputs folder is used for final manufacturing exports that need to be archived (e.g., version-tagged Gerbers for each PCB rev), consider splitting that directory into two: one for temporary previews, and another for release-grade exports.

Advanced: Modular Reuse with Git Submodules

If you find yourself using the same footprint libraries, templates, or symbol sets across many projects, don’t copy-paste them. Instead, house them in their own repository and bring them into your project structure using a Git submodule.

Example:

git submodule add https://github.com/myteam/kicad-libs.git libs/

Now your project can reference things like:

${KICAD_LIBS}/my_custom.pretty

Just remember: everyone cloning the repo needs to initialize submodules:

git clone --recurse-submodules https://github.com/myteam/my_project.git

or manually:

git submodule init
git submodule update

This gives you the best of both worlds: centralized part management and clean, reproducible board repositories.