Freecad Scripts

FreeCAD scripts

Translate natural language CAD tasks into production-quality FreeCAD Python code that handles documents, geometry, GUI availability, recompute, selection, and macro execution safely.

When to invoke

• "Write a FreeCAD macro to create this model."
• "Build a parametric FeaturePython object."
• "Script Part, Mesh, or Sketcher geometry in FreeCAD."
• "Create a PySide dialog or workbench command for FreeCAD."
• "Automate FEM, Path, TechDraw, or Coin3D scenegraph work."

Prerequisites and context

• FreeCAD installed; 0.19+ is workable, 0.21+/1.0+ is preferred for newer APIs.
• Python 3.x is bundled with FreeCAD.
• PySide2 and Pivy are bundled for GUI and Coin3D work in typical FreeCAD installs.
• Guard GUI-only code with if FreeCAD.GuiUp: so macros can fail gracefully in headless execution.

FreeCAD Python environment

Key modules and aliases:

import FreeCAD          # core module, often aliased as App
import FreeCADGui       # GUI module, often aliased as Gui; GUI mode only
import Part             # BRep/OpenCASCADE shapes
import Mesh             # triangulated meshes
import Sketcher         # 2D constrained sketches
import Draft            # 2D drawing tools
import Arch             # Arch/BIM workbench
import Path             # Path/CAM workbench
import FEM              # FEM workbench
import TechDraw         # replaces Drawing
import BOPTools         # boolean operations
import CompoundTools    # compound shape utilities

Document model essentials:

doc = FreeCAD.newDocument("MyDoc")
doc = FreeCAD.ActiveDocument
box = doc.addObject("Part::Box", "MyBox")
box.Length = 10.0
box.Width = 10.0
box.Height = 10.0
doc.recompute()
obj = doc.getObject("MyBox")
obj = doc.MyBox
doc.removeObject("MyBox")

Macro pattern

# -*- coding: utf-8 -*-
# FreeCAD Macro: MyMacro
# Description: Brief description of what the macro does
# Author: YourName
# Version: 1.0
# Date: 2026-04-07

import FreeCAD
import Part
from FreeCAD import Base

if FreeCAD.GuiUp:
    import FreeCADGui
    from PySide2 import QtWidgets, QtCore

def main():
    doc = FreeCAD.ActiveDocument
    if doc is None:
        FreeCAD.Console.PrintError("No active document
")
        return
    if FreeCAD.GuiUp:
        sel = FreeCADGui.Selection.getSelection()
        if not sel:
            FreeCAD.Console.PrintWarning("No objects selected
")
    doc.recompute()
    FreeCAD.Console.PrintMessage("Macro completed
")

if __name__ == "__main__":
    main()

Selection and console APIs to preserve:

sel = FreeCADGui.Selection.getSelection()
sel_ex = FreeCADGui.Selection.getSelectionEx()
for selobj in sel_ex:
    obj = selobj.Object
    for sub in selobj.SubElementNames:
        shape = obj.getSubObject(sub)
FreeCADGui.Selection.addSelection(doc.MyBox)
FreeCADGui.Selection.addSelection(doc.MyBox, "Face1")
FreeCADGui.Selection.clearSelection()
FreeCAD.Console.PrintMessage("Info message
")
FreeCAD.Console.PrintWarning("Warning message
")
FreeCAD.Console.PrintError("Error message
")
FreeCAD.Console.PrintLog("Debug/log message
")

Compensation rules

Always call doc.recompute() after modifications.

Progressive disclosure and bundled resources

• references/freecad-implementation-patterns.md: detailed FreeCAD API concepts, FeaturePython, GUI, Coin3D, workbench, and reusable patterns.
• references/scripting-fundamentals.md: document model, console, and core scripting.
• references/geometry-and-shapes.md: Part, Mesh, Sketcher, and topology.
• references/parametric-objects.md: FeaturePython, properties, and scripted objects.
• references/gui-and-interface.md: PySide, dialogs, task panels, and Coin3D.
• references/workbenches-and-advanced.md: workbenches, macros, FEM, Path, and recipes.

Compatibility vocabulary

Preserve these legacy terms, API names, command placeholders, and literal phrases when applying or migrating this skill:

• PySide/Qt
• bevel/chamfer
• built-in
• edges/fillet
• merge/combine/join
• quasi-code
• sub-elements
• sub-shape
• subtract/cut/remove
• topic-organized

Output template

## FreeCAD script result

**Status:** script-created | guidance-only | blocked
**Runtime:** FreeCAD Python macro | console snippet | workbench command

### Files or code
- `<path or snippet>`: <purpose>

### API coverage
| Area | APIs used | Notes |
| --- | --- | --- |
| Document | `FreeCAD.ActiveDocument`, `doc.recompute()` | <notes> |
| Geometry | `Part.makeBox()` / other APIs | <notes> |
| GUI | `FreeCAD.GuiUp` / PySide / selection | <notes> |

### Validation
- <how to run in FreeCAD and expected result>

Quality gate

• The script imports only FreeCAD modules needed for the task.
• GUI-dependent code is guarded with if FreeCAD.GuiUp:.
• Document creation, object naming, and doc.recompute() are handled.
• Units default to millimeters unless the user specified otherwise.
• Geometry operations use the correct Part, Mesh, Sketcher, Draft, Arch, Path, FEM, TechDraw, BOPTools, or CompoundTools APIs.
• Console messages use FreeCAD.Console.PrintMessage, PrintWarning, PrintError, or PrintLog.
• Bundled references are used for FeaturePython, GUI, Coin3D, workbench, or advanced patterns when needed.

References

• Writing Python code
• Manipulating FreeCAD objects
• Vectors and Placements
• Creating and manipulating geometry
• Creating parametric objects
• Creating interface tools
• Python
• Introduction to Python
• Python scripting tutorial
• FreeCAD scripting basics
• Gui Command