How to Export STEP Files from KiCad: Complete Guide for ECAD-MCAD Integration

After spending years designing boards in KiCad and handing them off to mechanical engineers working in SolidWorks and Fusion 360, I’ve learned that the STEP export process isn’t always as straightforward as it should be. KiCad handles 3D models differently than commercial tools, and understanding this difference is the key to getting clean exports that your mechanical team can actually use. This guide covers everything from basic exports to troubleshooting the notorious “Cannot add a VRML model to a STEP file” error.

What Is a STEP File and Why Export from KiCad?

STEP (Standard for the Exchange of Product model data) is an ISO-standardized CAD format (ISO 10303-21) that enables data exchange between different mechanical design software. When you export a STEP file from KiCad, you create a 3D model of your PCB assembly that mechanical engineers can import into their MCAD tools for enclosure design, clearance checking, and physical integration.

The critical use case is fit verification. When your PCB needs to mount inside an enclosure with specific connector positions, switch access, and display cutouts, your mechanical engineer needs accurate dimensional data. STEP files provide this with the precision required for tooling decisions.

What Gets Exported in a KiCad STEP File

Element	Included	Notes
Board substrate	Yes	Based on board outline and stackup thickness
Board cutouts	Yes	Internal cutouts export correctly
Component 3D models	Conditional	Only STEP models export; VRML requires substitution
Mounting holes	Yes	Part of board geometry
Copper traces	Optional	Available in KiCad 7+ with “Include tracks” option
Silkscreen	No	Not included in STEP format
Solder mask color	No	Not part of STEP geometry

Understanding these limitations upfront prevents the frustrating discovery that your beautiful 3D viewer rendering doesn’t translate directly to STEP output.

Understanding VRML vs STEP Models in KiCad

This is where most KiCad users run into problems. KiCad’s default 3D libraries include two file formats for each component:

Format	Extension	Purpose	STEP Export Compatible
VRML	.wrl	Visual rendering in 3D viewer	No (requires substitution)
STEP	.step, .stp	MCAD integration	Yes

VRML files contain material properties and colors that make the 3D viewer look realistic. However, VRML is a mesh-based visualization format—not a CAD format—and cannot be directly included in STEP exports. This mismatch causes the common error message: “Cannot add a VRML model to a STEP file.”

The official KiCad libraries include both formats for most components, but the footprints often reference only the VRML file by default. This creates the situation where your board looks perfect in the 3D viewer but exports with missing components.

Step-by-Step Guide to Export STEP Files from KiCad

The native STEP export in KiCad has improved significantly in recent versions. Here’s how to use it effectively.

Basic STEP Export from PCB Editor

1. Open your PCB design in KiCad’s PCB Editor
2. Verify your design in the 3D Viewer (View → 3D Viewer or Alt+3)
3. Navigate to File → Export → STEP
4. Configure export options in the dialog (detailed below)
5. Choose your save location and filename
6. Click Export

The export dialog provides several options that significantly affect your output quality.

KiCad STEP Export Options Explained

Option	Description	Recommended Setting
Coordinate origin	Reference point for model positioning	Grid origin (for consistent MCAD alignment)
Output file	Destination path and filename	Use .step extension
Substitute similarly named models	Replaces VRML with STEP models automatically	Enable this
Overwrite existing file	Replace without prompting	Enable for iterative workflows
Export board outline	Include the PCB substrate	Always enable
Export components	Include 3D component models	Enable for full assembly
Export tracks	Include copper traces (KiCad 7+)	Enable if needed for visualization
Export zones	Include copper pours (KiCad 7+)	Usually disable (increases file size)

The Critical Setting: Substitute Similarly Named Models

This checkbox is the solution to most STEP export problems. When enabled, KiCad automatically looks for a STEP file with the same base name as the referenced VRML file. For example:

• Footprint references: Resistors_SMD.3dshapes/R_0603_1608Metric.wrl
• KiCad substitutes: Resistors_SMD.3dshapes/R_0603_1608Metric.step

Without this option enabled, you’ll see the “Cannot add a VRML model to a STEP file” message for every component using VRML models, and your export will contain only the bare board.

Troubleshooting Common KiCad STEP Export Problems

Over years of exporting boards from KiCad, I’ve encountered these issues repeatedly. Here’s how to solve them.

Problem: “Cannot add a VRML model to a STEP file” Errors

Symptom: Export log shows multiple warnings about VRML models, resulting in bare board without components.

Solution: Enable “Substitute similarly named models” in the export dialog. This tells KiCad to look for STEP equivalents of VRML models.

If errors persist after enabling substitution, the component likely lacks a STEP model entirely. You have three options:

Option	Effort	Result
Download STEP model from manufacturer	Low	Best quality
Download from SnapEDA/Ultra Librarian	Low	Good quality
Create simple model in FreeCAD	Medium	Adequate for fit checking

Problem: Components Missing Despite STEP Models Existing

Symptom: Some components appear in 3D viewer but not in exported STEP file.

Causes and Solutions:

Cause	Solution
Path variables not resolving	Check Preferences → Configure Paths; verify KICAD6_3DMODEL_DIR or KICAD7_3DMODEL_DIR
Model file permissions	Verify read access to 3D model directories
Corrupted STEP file	Re-download or regenerate the 3D model
Model path uses ${KIPRJMOD} incorrectly	Use absolute paths or verify project directory structure

Problem: Export Takes Extremely Long Time

Symptom: Export hangs or takes many minutes for complex boards.

Solutions:

1. Disable “Export zones” unless copper pours are specifically needed
2. Disable “Export tracks” for initial mechanical fit checks
3. Reduce model complexity by using simplified 3D models for passives
4. Export without components first to verify board geometry

Problem: File Size Too Large

Symptom: STEP file is hundreds of megabytes, too large for MCAD software to handle efficiently.

Solutions:

1. Disable track and zone export
2. Use simpler 3D models for standard components
3. Export only critical components by temporarily removing 3D model references from passives
4. Consider exporting as VRML first if only visualization is needed

Advanced STEP Export: Using the Command Line

KiCad includes a powerful command-line interface for automated exports. This is particularly useful for CI/CD pipelines or batch processing.

Basic Command-Line STEP Export

bash

kicad-cli pcb export step –subst-models -o output.step input.kicad_pcb

Command-Line Options for STEP Export

Flag	Description
–output, -o	Output filename
–subst-models	Substitute VRML with STEP (essential)
–force, -f	Overwrite existing files
–grid-origin	Use grid origin as reference
–drill-origin	Use drill/place origin as reference
–no-unspecified	Exclude components without 3D models
–no-dnp	Exclude Do Not Populate components
–board-only	Export only the board, no components
–include-tracks	Include copper traces
–include-zones	Include copper zones/pours
–min-distance	Minimum distance for curve approximation

Example: Production-Quality Export Script

bash

#!/bin/bashkicad-cli pcb export step \  –subst-models \  –force \  –grid-origin \  –no-dnp \  -o “${PROJECT_NAME}_assembly.step” \  “${PROJECT_NAME}.kicad_pcb”

Using KiCad StepUp with FreeCAD

For advanced users who need more control over the export process, KiCad StepUp is a FreeCAD workbench that provides enhanced ECAD-MCAD integration.

What KiCad StepUp Offers

Feature	Benefit
Direct .kicad_pcb import	No intermediate export needed
Bi-directional editing	Push board outline changes back to KiCad
Model alignment tools	Precisely position 3D models on footprints
STEP model library creation	Generate matched STEP/VRML pairs

Installing KiCad StepUp

1. Install FreeCAD (version 0.19 or later recommended)
2. Open FreeCAD → Tools → Addon Manager
3. Search for “KiCad StepUp”
4. Click Install
5. Restart FreeCAD

Basic StepUp Workflow

1. Open FreeCAD and switch to KiCad StepUp workbench
2. File → Open → Select your .kicad_pcb file
3. StepUp loads the board and attempts to find matching STEP models
4. Adjust any misaligned components using StepUp tools
5. Select all objects (Ctrl+A)
6. File → Export → STEP with colors (*.step)

This workflow provides more control than native KiCad export and can resolve issues with problematic models.

Alternative Export Formats from KiCad

STEP isn’t the only 3D export option. Depending on your needs, other formats might work better.

Format	Extension	Best For	Notes
STEP	.step, .stp	MCAD integration	Universal CAD compatibility
VRML	.wrl	Visualization	Includes colors/materials, not CAD-compatible
IDF	.emn, .emp	Legacy MCAD exchange	Older format, limited features
GLB/GLTF	.glb	Web visualization	KiCad 8+ feature
PLY	.ply	3D printing/scanning	Mesh format
STL	.stl	3D printing	No color, mesh only

For most mechanical integration workflows, STEP remains the best choice due to universal support across MCAD platforms.

Setting Up 3D Models for Reliable STEP Export

The key to consistent STEP exports is ensuring your components have proper STEP models assigned.

Verifying 3D Model Assignments

1. Open your PCB in the PCB Editor
2. Double-click a component to open Properties
3. Click the “3D Models” tab
4. Verify both the path and that the file exists

Adding STEP Models to Footprints

1. Open the Footprint Editor
2. Load the footprint to modify
3. Go to Footprint Properties → 3D Models tab
4. Click “Add 3D Model”
5. Navigate to your STEP file
6. Adjust scale (STEP models should use scale 1:1:1)
7. Adjust offset and rotation as needed
8. Save the footprint

3D Model Scale Reference

Model Source	Typical Scale Setting
KiCad official STEP	1:1:1
Manufacturer STEP	1:1:1 (verify units match)
VRML models	0.3937:0.3937:0.3937 (inch to mm)
FreeCAD exports	1:1:1

Useful Resources for KiCad STEP Export

Official KiCad Resources

Resource	Description	Link
KiCad Documentation	Official PCB Editor manual	docs.kicad.org
KiCad 3D Libraries	Official STEP/VRML models	gitlab.com/kicad/libraries/kicad-packages3D
KiCad StepUp	FreeCAD workbench	kicad.org/external-tools/stepup
KiCad CLI Reference	Command-line documentation	docs.kicad.org (CLI section)

3D Model Download Sources

Source	Description	Formats
SnapEDA	Free component libraries	STEP, VRML, KiCad native
Ultra Librarian	Manufacturer-sourced models	STEP, various
3D ContentCentral	Dassault-hosted library	STEP, multiple CAD formats
GrabCAD	Community models	STEP, various
Component Search Engine	SamacSys library	STEP, VRML
Manufacturer websites	Direct from component makers	Usually STEP

STEP File Viewers (Free)

Tool	Platform	Notes
FreeCAD	Windows, Mac, Linux	Full CAD capability, KiCad StepUp support
Fusion 360 (Personal)	Windows, Mac	Free for hobbyists
eDrawings	Windows, Mac	Free viewer from SolidWorks
CAD Exchanger	Windows, Mac, Linux	Viewer with format conversion

Frequently Asked Questions

Why does my STEP export only show the bare board without components?

This happens when components use VRML (.wrl) 3D models instead of STEP models. Enable “Substitute similarly named models” in the export dialog. KiCad will automatically look for STEP files with matching names. If substitution doesn’t work, the component lacks a STEP model entirely—you’ll need to download or create one.

Can I export copper traces and silkscreen in the STEP file?

KiCad 7 and later versions support exporting copper traces via the “Include tracks” and “Include zones” options in the STEP export dialog. Silkscreen is not included in STEP exports because STEP is a geometry format, not a visual rendering format. For visualizations including silkscreen, export as VRML instead.

What’s the difference between exporting from KiCad directly versus using FreeCAD StepUp?

Native KiCad export is faster and simpler for straightforward boards. FreeCAD StepUp provides more control: you can adjust model positions, fix alignment issues, modify the board outline, and access FreeCAD’s full CAD capabilities. Use StepUp when native export produces unsatisfactory results or when you need bi-directional editing.

How do I fix components that are misaligned in the STEP export?

Component alignment issues stem from incorrect offset or rotation values in the footprint’s 3D model settings. Open the footprint in the Footprint Editor, go to the 3D Models tab, and adjust X/Y/Z offset and rotation values. The 3D viewer preview helps you verify alignment before committing changes.

Why is my exported STEP file so large?

Large file sizes typically result from enabling track and zone export, which converts all copper geometry to 3D objects. For mechanical fit checking, disable these options—the board outline and components are usually sufficient. Complex 3D models with high polygon counts also increase file size; consider using simplified models for passive components.

Best Practices for KiCad STEP Export Workflow

Establishing consistent practices prevents the common issues that derail ECAD-MCAD collaboration.

Before Starting Your Design

• Verify your component library has STEP models for critical components
• Confirm 3D model paths are correctly configured in Preferences
• Use official KiCad libraries when possible (they include matched STEP/VRML pairs)

Before Exporting

• Check the 3D viewer to verify all components appear correctly
• Note any components showing as missing models
• Verify board thickness is correctly set in Board Setup → Physical Stackup

After Exporting

• Open the STEP file in FreeCAD or another viewer to verify contents
• Check that critical components (connectors, switches, tall parts) exported correctly
• Document any limitations when sharing with mechanical team

Conclusion

Exporting STEP files from KiCad requires understanding the distinction between VRML visualization models and STEP CAD models. The key to successful exports is enabling the “Substitute similarly named models” option and ensuring critical components have STEP models available.

For most designs, the native KiCad STEP export works well once properly configured. For complex boards or when you need more control, KiCad StepUp with FreeCAD provides advanced capabilities. Either way, investing time in proper 3D model setup pays dividends when your PCB drops into the mechanical assembly and fits correctly the first time.

The few minutes spent verifying 3D models and configuring export settings saves hours of back-and-forth with your mechanical team—and potentially prevents expensive mechanical redesigns late in the project.