Power users hub

Other languages:

This is the place to come if you are an experienced user and want to learn more about customizing and extending FreeCAD.

FreeCAD is extensible by Python code that is run directly in the Python console, or that is loaded from modules at startup. This means that you can modify FreeCAD without needing to recompile the program. For example, you can:

Create and modify geometry: you can create a new object type, either from scratch or by adapting an existing type.
Create custom tools and commands: add your own set of tools that run your code.
Modify the interface: create toolbars to put your tools, create special windows, panels, or interfaces for interacting with your tools.
Modify the scenegraph representation: FreeCAD has separate processes for building up the geometry and displaying that geometry on screen. You have full access to the way the scene contents are displayed on screen, therefore you can modify that representation, interact with it, or add custom behaviour to it. You can also add custom screen widgets, like information, draggers, anchors or temporary entities.

If you'd like to contribute content to these pages, request a wiki account with editor permissions in the forum, and read the WikiPages for the general guidelines that you should follow. For other ways to contribute with the project, see the Help FreeCAD page.

Customizing FreeCAD

Interface Customization: Starting with the beginning: Toolbars and shortcuts
Working with Macros: Easily record often repeated tasks or Python code
Macros recipes
Customize Toolbars
Installing more workbenches

Scripting in FreeCAD

General

Scripting and Macros - A list of relevant wiki pages
Introduction to Python - See also other Python tutorials at the bottom of this page
FreeCAD scripting tutorial - A general look at Python scripting in FreeCAD
FreeCAD Scripting Basics: Well, the basics
FreeCAD Manual - Section Python Scripting: Multi-chapter introduction to Python Scripting in FreeCAD
Gui Command: Adding custom commands to the GUI
Using mixed Units in FreeCAD
Profiling the Python code
Debugging the Python code
Python Development Environment - A simplistic development environment for Python within FreeCAD

Modules

The functionality of FreeCAD is separated in Modules which deal with special data types and applications. FreeCAD has built-in modules and Extension Modules (plug-ins). Once plugin modules are installed, they become availible to you as easily as the built-in modules. The modules described below are the default modules, includeed in every FreeCAD installation.

The Builtin modules are the principal FreeCAD modules. They contain tools for manipulating general FreeCAD configurations, documents and their contents.
Workbench creation shows you how to create your own workbench

Working with Meshes

Mesh Scripting: How to interact with the Mesh Workbench

Working with Parts

The Part Workbench: How Open CASCADE Technology tools and structure is used in FreeCAD
Topological data scripting: How to interact with the Part Module
PythonOCC: How to unleash the whole Open CASCADE power
Mesh to Part: Converting between object types

Accessing the Coin scenegraph

The Coin/Inventor scenegraph: How the FreeCAD scene representation works
Pivy: How to access and modify the scenegraph

Controlling the Qt interface

PySide: How to access the interface, and modify its contents
Using the FreeCAD GUI in another Qt application with PyQt

Working with parametric objects

Scripted objects: how to make 100% Python-scripted objects.
- Scripted objects with attachment: how to make scripted objects attachable to other objects.
- Scripted objects saving attributes: how to save and restore attributes of the proxy class with dumps and loads.
- Scripted objects migration: how to migrate old scripted objects to a new class.

Examples

Code snippets : A collection of pieces of FreeCAD Python code, to serve as ingredients in your scripts...
Line drawing function: How to build a simple tool to draw lines
Dialog creation: How to construct dialogs with Qt designer, and use them in FreeCAD
Embedding FreeCAD: How to import FreeCAD as a Python module in other applications
The Draft Workbench adds basic 2d drawing functions to freecad. It is written entirely in Python, so it can be a good example if you want to write your own modules.
FreeCAD vector math library : A couple of handy functions to manipulate FreeCAD vectors. This library is also included in the Draft module.

API Functions

The complete API documentation of FreeCAD is located at https://www.freecadweb.org/api/ . It contains both C++ and Python APIs, and is not totally well formatted yet, which can be confusing when looking for python-only code. An easier to browse version can be found here. Note that it can be incomplete, since it is updated manually. For more accurate information, browse the modules directly from FreeCAD's Python console.

Related: Exposing C++ to Python

Advanced modification

Start up and Configuration: Startup and command line options
Installing on Windows: Using the windows installer
Compiling FreeCAD on Windows and Compiling FreeCAD on Linux
Branding: Simple modifications you can do to the source code to change some aspects of FreeCAD
Extra python modules : Extend the FreeCAD python interpreter with these powerful modules!

Python tutorials

These are good generic tutorials, not specific to FreeCAD, that might interest you if you are totally new to python.

Python

Official python tutorial - A very complete tutorial for discovering python
Non-programmer tutorial for python - an excellent wikibook
Python for newbies - one big tutorial covering all the basics

PySide - How to create and manage FreeCAD's Qt UI interface from python

PySide tutorial : A platform-agnostic tutorial showing the usage of PySide with examples
PySide/PyQt tutorial : A easy to read tutorial that covers PySide and PyQt with examples
PySide documentation : from the Qt Project (the people who wrote it all)
Using QtCreator in PySide : also from the Qt Project
PySide reference : endless detail on the minutiae of PySide and Qt, a reliable reference source
PySide code snippets : a searchable database of PySide code snippets

The following two references are PyQt specific (not PySide) but may offer some information of use:

Basic PyQt tutorial : A simple and short linux-based tutorial that will explain how to work with PyQt and Qt Designer
Programming Qt applications in python : A more in-depth tutorial covering all the process of working with qt and python

Pivy - How to interact with FreeCAD's 3D scenes

Pivy - Embedding a Dynamic Scripting Language into a Scene Graph Library : Thesis that explains Pivy in detail
High Level 3D Graphics Programming in Python : Pivy example from Pycon 2004
Introducing Pivy into studierstube (Mirror) : A paper that is not really a tutorial, but that illustrates well how Pivy works (requires an academic account)

Community projects

On the Community portal, you can find other FreeCAD-based projects run by the FreeCAD users community. If you are starting a new FreeCAD project, be sure to list it there! We also have a page with things you can do if you would like to Help FreeCAD.

Power user documentation

FreeCAD scripting: Python, Introduction to Python, Python scripting tutorial, FreeCAD Scripting Basics

Modules: Builtin modules, Units, Quantity
Workbenches: Workbench creation, Gui Commands, Commands, Installing more workbenches
Meshes and Parts: Mesh Scripting, Topological data scripting, Mesh to Part, PythonOCC

Parametric objects: Scripted objects, Viewproviders (Custom icon in tree view)
Scenegraph: Coin (Inventor) scenegraph, Pivy
Graphical interface: Interface creation, Interface creation completely in Python (1, 2, 3, 4, 5), PySide, PySide examples beginner, intermediate, advanced
Macros: Macros, How to install macros
Embedding: Embedding FreeCAD, Embedding FreeCADGui

Other: Expressions, Code snippets, Line drawing function, FreeCAD vector math library (deprecated)

Hubs: User hub, Power users hub, Developer hub