Headless FreeCAD/fr

Via the FreeCAD Python Console

This is an interactive mode where FreeCAD starts directly in a Python Console. This console is a fully functional Python environment with all of FreeCAD's Python modules, such as Part, BIM, and Draft, accessible through their public API. The core FreeCAD module is built-in, so it does not need to be imported explicitly during the console session. Other modules can be imported during the session (e.g. import Part), as needed.

This mode can be launched from the command line using either FreeCAD -c or FreeCADCmd. It offers the same functionality as the Python Console found within the full FreeCAD application.

It is best used for quickly testing Python code that accesses the FreeCAD API or for debugging small scripts that can be easily pasted into the console.

Via Python script

In this mode, FreeCAD is used as a standard Python library. This allows you to import its full Python API into any external Python script or application, treating it as a native module.

To enable this, the Python interpreter must be able to locate the FreeCAD library file, which is named FreeCAD.so on Linux and macOS or FreeCAD.pyd on other platforms. This is done by appending its directory to Python's search paths at the very beginning of your script. Once the path is set, the rest of the script can access the FreeCAD API like any other Python module.

Below is a simple example that creates a box and prints its volume and area:

This is a very powerful feature that unlocks the full capabilities of FreeCAD for automation and integration tasks. For example, one could write a script that leverages both the FreeCAD and Blender APIs to programmatically import objects from a .FCStd file directly into a Blender scene.

Note that this mode is intended for using the FreeCAD API without a GUI. While some GUI-related modules can be imported, API usage that directly accesses or manipulates GUI components is very limited and generally not supported in a headless context.

See Embedding FreeCAD.

Via shell script

You can also execute FreeCAD headlessly from a shell script by calling FreeCAD -c or FreeCADCmd followed by the necessary arguments.

A full list of available command-line arguments can be displayed by using the --help flag. Here is an example of the help output for FreeCAD 1.0.2:

This method is ideal for automated tasks and continuous integration (CI) scripts. Common uses include executing the entire test suite with FreeCADCmd -t 0 or running tests for a specific module, such as FreeCADCmd -t TestArch (all BIM Workbench tests) or FreeCADCmd -t TestArch.TestWall (only BIM Workbench's wall tests).

Executing Python code directly

FreeCAD's command-line executables can also function as specialized Python interpreters, allowing for the direct execution of Python code. This provides a convenient and powerful alternative to embedding FreeCAD within an external Python script.

Executing an Inline Script

You can pass a string of Python code directly as a single argument. This is useful for very short, single-purpose commands. Note that the command-line argument must not be a path to an existing file for this to work.

• Headless Mode: Using FreeCADCmd executes the code and then immediately exits. This is ideal for scripting.

$ FreeCADCmd "import Part; print(Part.makeBox(10,5,15).Volume)"

• Interactive Mode: Using FreeCAD -c executes the code and then opens an interactive Python console session. This is useful for quick tests where you may want to inspect the state afterwards.

$ FreeCAD -c "import Part; my_box = Part.makeBox(10,5,15)"

Executing a Script File

A more powerful method is to use FreeCAD to directly execute a Python script file. This is the recommended approach for any non-trivial headless task.

When a script is run this way, the FreeCAD environment is already configured. The key advantage is that the script does not need the sys.path.append() boilerplate code. The FreeCAD modules are immediately available for import.

For example, a file named create_box.py could contain:

import Part
# The FreeCAD module is already available, but it can be imported explicitly
import FreeCAD
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
# Create a new document and add a box to it
doc = FreeCAD.newDocument()
box_obj = doc.addObject("Part::Box", "MyBox")
doc.recompute()
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
# Export the part to a STEP file
Part.export([box_obj], "my_box_model.step")
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
print("Box created and exported successfully to my_box_model.step")

Running this script from the terminal is as simple as:

$ FreeCADCmd create_box.py
Box created and exported successfully to my_box_model.step