Skip to content

Installation

Jump to bottom
alf edited this page Apr 28, 2026 · 4 revisions

Installation

Requirements

Requirement Details
FreeCAD 1.0 or later (tested with 1.0.2)
Python 3.11+ (bundled with FreeCAD AppImage)
LLM provider Local Ollama or a cloud API key (Anthropic, OpenAI, Gemini, OpenRouter)
External dependencies None -- the workbench uses only Python stdlib

FreeCAD AI has zero external Python dependencies. It communicates with LLM providers using urllib, json, ssl, and threading from the standard library, so there is nothing to pip install.

Install Methods

Method 1: Symlink (Recommended for Development)

Symlinking lets you git pull updates without copying files again.

git clone https://github.com/ghbalf/freecad-ai.git
ln -s "$(pwd)/freecad-ai" ~/.local/share/FreeCAD/Mod/freecad-ai

The symlink target must be the repository root (the directory containing Init.py, InitGui.py, and the freecad_ai/ package).

Method 2: Direct Copy

git clone https://github.com/ghbalf/freecad-ai.git
cp -r freecad-ai ~/.local/share/FreeCAD/Mod/freecad-ai

To update later, git pull in your clone and copy again.

Method 3: FreeCAD Addon Manager

Submission to the FreeCAD Addon Manager registry is in progress (as of v0.12.0-alpha). The workbench now meets the Addon Academy quality requirements — FreeCAD-native preferences page, valid package.xml, LGPL-2.1-or-later SPDX identifier, zero external dependencies, GDPR-safe (LLM calls go to user-configured providers only), and the Qt compat shim that abstracts PySide2/PySide6.

Until the "Addon - Addition" issue is opened and merged on FreeCAD/FreeCAD-addons, please use Method 1 (symlink) or Method 2 (direct copy). This page will be updated with the actual install steps once the workbench appears in the Addon Manager.

Mod Directory Locations by Platform

Platform Path
Linux ~/.local/share/FreeCAD/Mod/
macOS ~/Library/Application Support/FreeCAD/Mod/
Windows %APPDATA%\FreeCAD\Mod\

FreeCAD also checks <install-dir>/share/freecad/Mod/ (the system Mod directory), but the user Mod directory above is the recommended location.

Verification

  1. Restart FreeCAD (or close and reopen it).
  2. Open the workbench selector -- click the dropdown in the main toolbar (it usually says "Start" or the name of the current workbench).
  3. Select "FreeCAD AI" from the list.
  4. The AI chat panel should appear as a docked widget on the right side of the window.
  5. A toolbar with "Open AI Chat" and "AI Settings" buttons should appear, and a "FreeCAD AI" menu should be added to the menu bar.

If the workbench appears but the chat panel does not open automatically, go to FreeCAD AI > Open AI Chat from the menu bar, or click the "Open AI Chat" toolbar button.

Troubleshooting

Workbench does not appear in the selector

  1. Check the Python console -- open it via View > Panels > Python Console (or View > Panels > Report View). Import errors during workbench loading are printed here.
  2. Verify the directory structure -- FreeCAD expects Init.py and InitGui.py at the top level of the Mod directory: 
    ~/.local/share/FreeCAD/Mod/freecad-ai/
    Init.py
    InitGui.py
    freecad_ai/
        __init__.py
        config.py
        ...
  3. Check the symlink -- if using Method 1, confirm the symlink points to the right place: 
    ls -la ~/.local/share/FreeCAD/Mod/freecad-ai
    The output should show an arrow pointing to your cloned repository.
  4. Check FreeCAD version -- the workbench requires FreeCAD 1.0+. Older versions may fail silently.

"No module named freecad_ai" error

The Init.py file adds the Mod directory to sys.path automatically. If you see this error:

  • Make sure the directory is named exactly freecad-ai (with a hyphen) under the Mod folder.
  • If you renamed it, update the directory name or adjust the path in Init.py.

Chat panel is blank or unresponsive

  • You have not configured an LLM provider yet. Open FreeCAD AI > AI Settings and follow the Configuration guide.
  • If using Ollama, make sure the Ollama server is running (see below).

Ollama Setup (Local Models)

Ollama lets you run LLMs locally with no API key and no cloud dependency. It is the easiest way to get started.

1. Install Ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# macOS
brew install ollama

# Windows
# Download from https://ollama.com/download

2. Pull a Model

# Recommended for tool calling (good balance of quality and speed)
ollama pull qwen3

# Alternatives
ollama pull llama3          # Meta's Llama 3 (8B, fast)
ollama pull qwen2.5-coder   # Alibaba's coding model
ollama pull deepseek-r1      # DeepSeek reasoning model

Choose a model that fits your hardware. Larger models produce better results but require more RAM/VRAM:

Model Parameters RAM Needed Quality
llama3 (8B) 8B ~6 GB Good for simple tasks
qwen3 (8B) 8B ~6 GB Good tool calling support
qwen2.5-coder (7B) 7B ~6 GB Strong at code generation
qwen3 (32B) 32B ~22 GB High quality, needs GPU
deepseek-r1 (70B) 70B ~45 GB Excellent, needs large GPU

3. Start the Server

Ollama runs as a background service. After installation it usually starts automatically. Verify:

# Check if Ollama is running
curl http://localhost:11434/api/tags

# If not running, start it
ollama serve

You should see a JSON response listing your pulled models.

4. Configure FreeCAD AI

  1. Open FreeCAD AI > AI Settings.
  2. Set Provider to Ollama.
  3. Base URL defaults to http://localhost:11434/v1 -- leave this as-is unless you changed Ollama's port.
  4. Set Model to the name you pulled (e.g., qwen3, llama3).
  5. Leave API Key empty (Ollama does not require one).
  6. Click Test Connection to verify.
  7. Click Save.

Ollama Tips

  • First request may be slow -- Ollama loads the model into memory on first use. Subsequent requests are fast. The HTTP timeout is set to 300 seconds to accommodate cold-loading of large models.
  • Context window -- FreeCAD AI does not override num_ctx. The model uses whatever context window it was loaded with.
  • GPU acceleration -- Ollama automatically uses your GPU if CUDA or Metal drivers are available. Check ollama ps to see if the model is running on GPU.
  • Remote Ollama -- if Ollama runs on a different machine, change the Base URL to http://<remote-ip>:11434/v1. Make sure Ollama is configured to listen on all interfaces (OLLAMA_HOST=0.0.0.0).

Next Steps

After installation, proceed to Configuration to set up your LLM provider, then Getting Started to build your first model.

FreeCAD AI Wiki

Clone this wiki locally