How to Import STEP Files in FreeCAD Using Python

This article explains how to programmatically import external STEP (.step or .stp) CAD files into FreeCAD using its built-in Python scripting environment. You will learn the primary methods for loading these files both with and without the graphical interface, the core modules required, and how to properly add the imported geometry to an active or new FreeCAD document.

Method 1: Using the Import Module (Recommended)

The most direct and standard way to import a STEP file in FreeCAD via Python is using the Import module (or ImportGui if running in the graphical user interface). This method automatically handles hierarchy, colors, and assembly structures.

For Non-GUI (Headless / Console) Mode

If you are running FreeCAD from the command line or in a batch script without the 3D viewer, use the Import module:

import FreeCAD
import Import

# Ensure an active document exists or create a new one
if FreeCAD.ActiveDocument is None:
    doc = FreeCAD.newDocument("ImportedDocument")
else:
    doc = FreeCAD.ActiveDocument

# Define the absolute path to your STEP file
file_path = "C:/path/to/your/model.step"

# Import the STEP file into the target document
Import.insert(file_path, doc.Name)

# Recompute the document to update geometry
doc.recompute()

For GUI Mode

If you are running the script inside FreeCAD's built-in Python console and want the 3D view to reflect the import immediately with full visual representation:

import FreeCAD
import ImportGui

if FreeCAD.ActiveDocument is None:
    doc = FreeCAD.newDocument("ImportedDocument")
else:
    doc = FreeCAD.ActiveDocument

file_path = "C:/path/to/your/model.step"

# Import with GUI support
ImportGui.insert(file_path, doc.Name)

FreeCAD.Gui.SendMsgToActiveView("ViewFit")
doc.recompute()

Method 2: Using the Part Module

If you only need the raw boundary representation (B-Rep) geometry as a single solid without retaining STEP assembly structures, colors, or metadata, use the Part module.

import FreeCAD
import Part

# Ensure an active document exists
if FreeCAD.ActiveDocument is None:
    doc = FreeCAD.newDocument("PartDocument")
else:
    doc = FreeCAD.ActiveDocument

file_path = "C:/path/to/your/model.step"

# Read the shape from the STEP file
shape = Part.Shape()
shape.read(file_path)

# Create a Part feature and assign the imported shape
part_feature = doc.addObject("Part::Feature", "StepPart")
part_feature.Shape = shape

# Recompute the document
doc.recompute()

Best Practices for File Paths

• Path Separators: Always use forward slashes (/) or raw Python strings (r"C:\path\to\file.step") to avoid escaping errors on Windows systems.
• Absolute Paths: Use absolute paths rather than relative paths to avoid resolution issues depending on FreeCAD's working directory.