How to Install Python Modules for FreeCAD

This guide explains how to install third-party Python packages for use within FreeCAD extensions, workbenches, and macros. Because FreeCAD uses its own Python environment on Windows and macOS—and typically uses the system Python environment on Linux—adding external libraries requires targeting the correct interpreter. Below, you will find straightforward methods to install external modules directly using the built-in FreeCAD Python console, your operating system's terminal, or a dedicated target directory.

Identify FreeCAD’s Python Interpreter

FreeCAD executes scripts using an embedded or linked Python interpreter. Before installing packages, verify which Python environment FreeCAD is running:

  1. Open FreeCAD.
  2. Ensure the Python console is visible (View > Panels > Python console).
  3. Type the following commands and press Enter:
import sys
print(sys.executable)

The output displays the exact path to the Python binary used by FreeCAD.

Method 1: Install Directly from the FreeCAD Python Console

The simplest, cross-platform way to install a module is using Python's built-in subprocess module directly inside FreeCAD. This ensures that the package is installed to the exact environment FreeCAD runs on.

  1. Open FreeCAD and access the Python console.
  2. Run the following code block, replacing package_name with your desired module (for example, scipy or requests):
import subprocess
import sys

subprocess.run([sys.executable, "-m", "pip", "install", "package_name"])
  1. Wait for the process to complete. Once finished, verify the installation:
import package_name
print(package_name.__file__)

If no errors appear, the module is ready for use in your macros and workbenches.

Method 2: Install via the Operating System Terminal

If you prefer using a system terminal or need to install multiple packages from a requirements.txt file, invoke FreeCAD's bundled Python binary directly from your command line.

Windows

Open Command Prompt as an administrator and run:

"C:\Program Files\FreeCAD 1.0\bin\python.exe" -m pip install package_name

(Adjust the directory path to match the output from sys.executable.)

macOS

Open Terminal and run:

/Applications/FreeCAD.app/Contents/Resources/bin/python -m pip install package_name

Linux

On Linux distributions, FreeCAD typically uses your system-wide Python installation. Install packages through your system's package manager or using pip:

pip install --user package_name

Method 3: Install to FreeCAD's User Addon Directory

If your FreeCAD installation directory is write-protected (common in corporate or restricted environments), install packages into your personal FreeCAD configuration folder using pip's --target flag.

  1. Find your user directory inside the FreeCAD Python console:
import FreeCAD
print(FreeCAD.getUserAppDataDir())
  1. Open your system terminal and install the package to the site-packages or Mod folder inside that path:
python -m pip install --target="<UserAppDataDir>/site-packages" package_name
  1. If the directory is not automatically on your Python path, append it at the beginning of your FreeCAD macro or workbench:
import sys
import FreeCAD

user_site = FreeCAD.getUserAppDataDir() + "site-packages"
if user_site not in sys.path:
    sys.path.append(user_site)

import package_name