Run FreeCAD Headless for Server Processing

FreeCAD can be run in a headless environment for server-side processing, automated workflows, and cloud-based CAD pipelines. This guide explains how to execute FreeCAD without a graphical user interface (GUI), covering the native command-line binaries, utilizing FreeCAD as a standalone Python module, managing virtual framebuffers for off-screen rendering, and deploying workloads via Docker.

Running FreeCAD Without a GUI

FreeCAD provides built-in mechanisms to operate entirely without a desktop environment. This capability makes it suitable for automated CAD conversions, parametric model generation via web APIs, and continuous integration testing.

Depending on your distribution and installation method, there are three primary ways to interact with FreeCAD in a headless setup:

1. Using the freecadcmd Executable

Most Linux and Windows distributions of FreeCAD include a separate executable specifically designed for command-line execution: freecadcmd.

To run an interactive Python shell inside the FreeCAD environment:

freecadcmd

To execute a non-interactive Python script and exit automatically upon completion:

freecadcmd script.py

This executable does not load the GUI libraries (such as Qt or FreeCADGui), drastically reducing memory overhead and eliminating the need for an active X11 or Wayland display server.

2. Using Command-Line Flags with the Main Executable

If freecadcmd is unavailable, the standard freecad binary provides flags to suppress GUI initialization:

  • Console Mode: freecad --console launches an interactive terminal prompt without a GUI window.
  • Script Execution: freecad script.py runs a specified script. If the script does not call FreeCADGui, it executes in the background without drawing a window.

3. Importing FreeCAD as a Python Module

FreeCAD's core architecture allows it to be imported directly into any external Python 3 interpreter. This approach is ideal for integrating FreeCAD into existing web services (such as Flask, FastAPI, or Django) or background task workers (such as Celery).

To use FreeCAD as a library:

  1. Locate your FreeCAD bin and lib directories.
  2. Add these paths to your system's PYTHONPATH environment variable or append them using sys.path.append().
import sys
sys.path.append("/usr/lib/freecad/lib")

import FreeCAD
import Part

# Create a simple box and export it
doc = FreeCAD.newDocument("HeadlessDoc")
box = doc.addObject("Part::Box", "MyBox")
box.Length = 10.0
box.Width = 20.0
box.Height = 30.0
doc.recompute()

Part.export([box], "output.step")

Handling Off-Screen Rendering and FreeCADGui

While geometry creation, Boolean operations, and file conversions (e.g., STEP to STL) require only the core FreeCAD and Part modules, certain operations—such as generating technical drawings or rendering 3D preview images—depend on the FreeCADGui and Coin3D modules.

If your script requires FreeCADGui on a headless server:

  1. Use a Virtual Framebuffer: Install xvfb (X Virtual FrameBuffer) to emulate a display server in system memory.

    sudo apt-get install xvfb

  2. Execute within xvfb-run: Wrap your execution command with xvfb-run:

    xvfb-run -a freecad script.py

    This provides the necessary display context to initialize Qt and OpenGL without physical graphics hardware.

Containerization with Docker

Running FreeCAD headless inside Docker is the industry standard for production deployments. A minimal Ubuntu or Debian base image can be configured with FreeCAD and executed on demand:

FROM ubuntu:22.04

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y \
    freecad \
    xvfb \
    python3 \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . /app

CMD ["freecadcmd", "main.py"]

Common Server-Side Use Cases

  • File Format Conversion: Automatically converting uploaded CAD files (STEP, IGES, BREP) into lightweight web formats (STL, OBJ, GLTF).
  • Parametric Web Configurators: Modifying spreadsheet parameters inside a template FreeCAD document based on user input, recomputing the geometry, and serving the output file dynamically.
  • Automated Validation: Checking parts for volumetric consistency, interference, or bounding box constraints inside continuous integration (CI) environments.