How to Manually Install FreeCAD Workbenches

This guide explains how to manually install third-party workbenches into FreeCAD by downloading the extension source files and placing them into the application's dedicated user directory. While the built-in Addon Manager is the standard way to install plugins, manually installing a workbench is an essential skill when working offline, installing custom or unlisted modules, or troubleshooting failed automatic downloads.

Step 1: Locate the FreeCAD User Directory

FreeCAD stores user-added workbenches in a specific subfolder named Mod. You must navigate to this location on your operating system:

  • Windows: Press Win + R, type %APPDATA%\FreeCAD\Mod, and press Enter. (Full path typically: C:\Users\<YourUsername>\AppData\Roaming\FreeCAD\Mod\)
  • Linux: Open your file manager or terminal and go to ~/.local/share/FreeCAD/Mod/ (or ~/.FreeCAD/Mod/ on older versions).
  • macOS: Open Finder, press Cmd + Shift + G, and navigate to ~/Library/Application Support/FreeCAD/Mod/.

Note: If the Mod folder does not exist inside your FreeCAD directory, create a new folder and name it Mod.

Step 2: Download the Workbench Files

Obtain the workbench code from its repository (typically GitHub or GitLab):

  1. Go to the project page of the workbench you want to install.

  2. Click the Code button and select Download ZIP.

  3. Alternatively, if you have Git installed, you can clone the repository directly inside the Mod directory via your terminal:

    git clone <repository-url>

Step 3: Extract and Structure the Folder

Proper folder structure is critical for FreeCAD to recognize the workbench.

  1. Extract the downloaded ZIP archive directly into your Mod directory.
  2. Open the extracted folder and verify that it contains the core workbench files, such as InitGui.py or Init.py.
  3. Remove branch suffixes from the folder name. For example, if GitHub downloads a folder named A2plus-master, rename the folder to simply A2plus.
  4. Ensure there is no redundant nesting. The path must be Mod/<WorkbenchName>/InitGui.py, not Mod/<WorkbenchName>/<WorkbenchName>/InitGui.py.

Step 4: Restart FreeCAD

  1. Close FreeCAD completely if it is currently running.
  2. Launch FreeCAD.
  3. Open the workbench dropdown menu on the top toolbar or navigate to View > Workbench.
  4. Select your newly installed workbench from the list to begin using it.