# kicadStepUp: bridging a KiCad board and a FreeCAD mechanical model > kicadStepUp is a FreeCAD workbench and macro that lets a KiCad board and a FreeCAD mechanical assembly be edited together, so a board outline can be pulled into the Sketcher, redrawn and pushed back, and a footprint can be placed against a 3D model with the alignment done in the mechanical tool. It is written in Python, ships as a FreeCAD add-on, and supports a wide range of FreeCAD and KiCad versions. **easyw/kicadStepUpMod** — kicadStepUp: ECAD to MCAD FreeCAD WorkBench - Repository: https://github.com/easyw/kicadStepUpMod - Stars: 699 · Forks: 85 - Language: Python - License: not declared - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/easyw-kicadstepupmod ## A workbench and a macro, not a plugin kicadStepUp is described as KiCad StepUp tools, which are a FreeCAD Macro and a FreeCAD WorkBench, and its purpose is mechanical collaboration between KiCad EDA and FreeCAD or another mechanical CAD tool. Shipping both forms matters because FreeCAD has two extension surfaces and they serve different needs. A workbench is a mode with its own toolbars, panels and commands, which is where the day-to-day work happens. A macro is a single command you can invoke from the Python console or bind to a shortcut, which is what you want for the scripted parts of the workflow. The repository structure is consistent with a mature add-on rather than a script collection. There are the FreeCAD module entry points Init.py and InitGui.py, a SaveSettings.py, a TranslateUtils.py, and the command modules kicadStepUpCMD.py and kicadStepUptools.py. There are parsers for each side of the exchange, kicad_parser.py and fcad_parser.py, plus a dxf_parser/ directory and ZipStepImport.py, which is the import path for STEP files that arrive zipped, a common packaging form for 3D component models. Beyond that there is the machinery that makes the round trip work: constrainator.py, which places a 3D model against a footprint, exchangePositions.py, expTree.py and explode.py for handling assemblies, selection2edges.py for turning a selection into board edges, and makefacedxf.py. There is a translations/ directory, a package.xml for distribution, an FC-Versions.txt recording the supported FreeCAD versions, and a changelog.txt. The license is the GNU Affero General Public License, and the repository licence field is recorded as unknown, so the AGPL statement in the README is the one to rely on. ## Pushing a board edge into the PCB and pulling it back out The feature list is the clearest description of the scope, and two entries are the heart of it. You can design a new PCB edge with the FreeCAD Sketcher and push it to an existing kicad_pcb board. And you can pull a PCB edge out of a kicad_pcb board, edit it in the FreeCAD Sketcher and push it back to KiCad. That is a two-way edge workflow, and it is the thing most people want from a bridge like this. The usual way to get a board outline into a mechanical CAD tool is to export a DXF, import it, clean it up and export something back. The DXF is a lossy, ambiguous format for this, and the edge is exactly the shape that needs to be exact because it has to match the milling operation. Working with the Sketcher rather than with imported curves is the substantive difference. A sketch in FreeCAD is a parametric, editable object, so you can pull the edge in, adjust it with constraints, and push back a shape that FreeCAD still knows how to reason about. The demo files in the repository include a footprint edge template, which suggests the same treatment applies to footprint outlines, not only to the board edge. The videos the README links show the two directions separately, one on a complex edge sketch pushed to the PCB and one on the push and pull of an edge, which is a reasonable way to teach the workflow since the two directions are separate operations rather than a single sync. The cheat sheet is a PDF in the demo directory, linked from the README, and it is the reference to keep open while working, since the commands are numerous and the naming is specific. ## Footprints, 3D models and the alignment problem The second half of the feature list is about getting a footprint and a 3D model to agree with each other, which is harder than it sounds. One entry loads a kicad_mod footprint into FreeCAD so the mechanical model can be aligned to the footprint precisely. Another converts the STEP 3D model of parts, the board and the enclosure to VRML with materials properties, for use inside KiCad, and another generates Blender compatible VRML files. The VRML path exists because KiCad's 3D viewer wants that format, and the reason the project converts rather than asking you to export VRML yourself is the materials, which are what make a part look right in the viewer. There is also a check for interference and collisions for enclosure and footprint design, and an entry to generate 3D FFC and FPC stiffener geometry from custom PCB user layers, which is a detail that tells you the tool is used by people building real hardware rather than demos. Two more entries extend the collaboration past geometry. You can design a new footprint in FreeCAD to get the power of the Sketcher in footprints, and the translation infrastructure is enabled, which in this context means a 3D model and a footprint can be associated so that they travel together. The demo directory shows what these workflows look like in practice. There is a flat cable FreeCAD file, a KiCAD footprint and model from 3D step data, an RF antenna footprint and a dxf for one, a microstrip RF filter footprint, a notch filter, a waveguide antenna, a splitter, a complex polyline footprint, an example folder for the FFC stiffener feature, and several demo boards including demo.kicad_pcb and empty board files for KiCad 5 and KiCad 6. There is a CrazyFlie image in the README, which is a real flight controller board and a good example of the kind of hardware this workflow suits. ## Installation through the add-on manager, with a Linux caveat The installation section has three routes, and the first is the one most people will try. You download and install the corresponding version of FreeCAD from the FreeCAD download page, and then either install the add-on automatically using the FreeCAD Add-on Manager, which is bundled into FreeCAD under the Tools menu, or manually by copying the kicadStepUpMod folder into the Mod sub-directory of the FreeCAD application, or manually by following the standard FreeCAD instructions for installing more workbenches. The manual routes matter for a specific reason. The add-on is not a Python package you pip install, it is a folder of FreeCAD modules that FreeCAD discovers at startup, and the Mod directory is where it has to live. If you are installing into a Flatpak or Snap build of FreeCAD, that directory is inside a sandboxed filesystem rather than the one you can see, which is the root of the known issues below. Two known issues are recorded. On Linux, FreeCAD Snap and Flatpak installs may need a mount bind to have access to the KiCad 3D models path, because the models live in the KiCad installation and the sandbox does not expose it. And on Linux, the FreeCAD add-on manager may fail to install for FreeCAD 1.0.1 and later. The second one is the practical reason to use the manual route on a recent Linux FreeCAD, and it is worth reading before you spend time on the automatic path. The support matrix is broad, and the project lists the requirements like this: ```text - **FreeCAD** **0.19, 0.20, 0.21, 0.22, 1.0** - **KiCAD** **5.1**, **6.x**, **7.x**, **8.x**, **9.x**, **10.x** - **KiCAD *10.99 nigthly* (partially supported)** ``` So KiCad 5.1 through 10.x are covered, with the 10.99 nightly only partially supported. The repository is not archived and the last push was on 2026-09-04, with no GitHub releases. ## AI-generated contributions are explicitly rejected The contributing section is short and unusually blunt, and it is worth quoting because it is a stated policy rather than an inference. It says that AI-generated contributions are not accepted, that all pull requests and issues must be written genuinely by the contributor, and that content generated by AI tools, including code, comments, commit messages, issue or pull request descriptions and documentation, will be rejected. For a repository that has been maintained for a long time, with a changelog, a package.xml, translations and a cheat sheet, that is a reasonable position. A tool like this accumulates a lot of small, correct, context-dependent edits to the CAD parsing code, and a patch that looks right but was written without the author understanding the geometry behind it is worse than no patch at all. It also means something for anyone who wants to help. A report of a bug with a reproduction, or a documentation fix written by hand, is welcome. A generated pull request is not going to be reviewed. The support channels are the two forums, the KiCad Info forum and the FreeCAD forum, and the README points at both for discussing the add-on or reporting issues, which is where a question about a specific geometry problem belongs, since the people who answer there are the people who use these tools daily. ## Conclusion kicadStepUp is worth installing if you design the electronics and the enclosure together, because the round trip it offers, a board edge drawn in the FreeCAD Sketcher and pushed back into the kicad_pcb file, removes the DXF shuffle that usually sits between the two tools, and the footprint placement workflow puts the 3D model and the footprint in one space. It is the wrong tool if your board is mechanically trivial, since the round trip is a lot of machinery for a single-board part, and it is the wrong tool if you cannot accept an add-on that patches into FreeCAD internals. Before you install it, verify three things yourself: that your FreeCAD version is one of the supported ones, since the list runs from 0.19 through 1.0, that your KiCad version is supported, with 10.x listed and the 10.99 nightly only partially supported, and that the add-on installs cleanly on your platform, because the README records a known failure of the FreeCAD add-on manager on Linux for FreeCAD 1.0.1 and later, and a known need for a mount bind on Linux for the KiCad 3D models path. ## FAQ ### What is kicadStepUp? It is a FreeCAD Macro and WorkBench for mechanical collaboration between KiCad EDA and FreeCAD or another mechanical CAD tool. It is written in Python, ships as the kicadStepUpMod folder for the FreeCAD Mod directory, and is licensed under the GNU Affero General Public License. ### Can I edit a KiCad board edge in FreeCAD and push it back? Yes, in both directions. You can design a new PCB edge with the FreeCAD Sketcher and push it to an existing kicad_pcb board, and you can pull a PCB edge out of a board, edit it in the Sketcher and push it back to KiCad. ### Which FreeCAD and KiCad versions does kicadStepUp support? The requirements list FreeCAD 0.19, 0.20, 0.21, 0.22 and 1.0, and KiCad 5.1, 6.x, 7.x, 8.x, 9.x and 10.x, with the KiCad 10.99 nightly only partially supported. The last push to the repository was on 2026-09-04 and there are no GitHub releases. ### How do I install the kicadStepUp add-on? Install FreeCAD itself, then either use the FreeCAD Add-on Manager under the Tools menu, copy the kicadStepUpMod folder into the Mod sub-directory of the FreeCAD application, or follow the standard instructions for installing more workbenches. On Linux with FreeCAD 1.0.1 or later the add-on manager may fail, and Snap and Flatpak installs may need a mount bind for the KiCad 3D models path. ### Does kicadStepUp accept AI-generated contributions? No. The contributing section states that AI-generated contributions are not accepted and that content generated by AI tools, including code, comments, commit messages, issue and pull request descriptions and documentation, will be rejected. Issues and pull requests must be written genuinely by the contributor. ## Sources - [easyw/kicadStepUpMod on GitHub](https://github.com/easyw/kicadStepUpMod) - [Issues](https://github.com/easyw/kicadStepUpMod/issues) - [README](https://github.com/easyw/kicadStepUpMod/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/easyw-kicadstepupmod