CookieCutter template for generating FreeCAD addon boilerplate.
Note
You do not need to fork this template to use it, just follow the "Quick Start" instructions below.
Important
Everything generated by this cookiecutter template is an example. Once the initial boilerplate is generated, modify/structure as you see fit.
There are a couple of methods to install uv, look at the docs here: https://docs.astral.sh/uv/getting-started/installation/
The Typical install on POSIX platforms is:
curl -LsSf https://astral.sh/uv/install.sh | shYou don't have to install cookiecutter or python by hand as uv will take care of that.
Launch cookiecutter and point it at the template repo:
uvx cookiecutter https://github.com/FreeCAD/Addon-Template.git --checkout cookieAnswer the questions:
[1/13] Addon name (MyAddon):
[2/13] Project directory (MyAddon):
[3/13] Python sub-module name (MyAddon):
[4/13] Name of the svg icon file (addon.svg):
[5/13] Name of the author/maintainer (me):
[6/13] Email of the author/maintainer (me@foobar.com):
[7/13] Short description of the addon (MyAddon does something cool.):
[8/13] Required pypi dependencies (optional, separated by comma. i.e. numpy,pillow) ():
[9/13] Initial version using format major.minor.review (0.1.0):
[10/13] Select addon_license
1 - LGPL-2.1-or-later
2 - LGPL-3.0-or-later
3 - GPL-3.0-or-later
4 - MIT
5 - CC0
6 - CC-BY-SA-4.0
7 - OTHER
Choose from [1/2/3/4/5/6/7] (1):
[11/13] Select assets_license
1 - CC-BY-SA-4.0
2 - CC0
3 - LGPL-2.1-or-later
4 - LGPL-3.0-or-later
5 - GPL-3.0-or-later
6 - MIT
7 - OTHER
Choose from [1/2/3/4/5/6/7] (1):
[12/13] Full url of the git repository (https://github.com/me/MyAddon):
[13/13] Name of the default git branch (main):Voila, the addon has been created in a directory under the current directory:
MyAddon/
├── freecad
│ └── MyAddon
│ ├── commands
│ │ ├── example_command.py
│ │ ├── example_manipulator.py
│ │ └── __init__.py
│ ├── example_workbench.py
│ ├── init_gui.py
│ ├── __init__.py
│ ├── resources
│ │ ├── docs
│ │ │ └── Overview.md
│ │ ├── icons
│ │ │ ├── MyAddon.svg
│ │ │ └── MyAddon-wb.svg
│ │ ├── __init__.py
│ │ ├── translations
│ │ │ ├── MyAddon_es-ES.ts
│ │ │ ├── README.md
│ │ │ └── update_translation.py
│ │ └── ui
│ └── version.py
├── LICENSE-Assets
├── LICENSE-Code
├── package.xml
├── pixi.toml
├── pyproject.toml
└── README.mdThe easiest way to install a newly created addon is to just symlink it into the Mod directory if your platform allows symlinks.
# cd to the Mod directory of your FreeCAD installation
cd <FreeCAD user's config directory>/Mod
ln -s <path to the created addon> MyAddonThe other option is to just copy your addon dir into <FreeCAD user's config directory>/Mod
| Platform | Typical Path |
|---|---|
| Windows | %APPDATA%\FreeCAD\Mod\ *(Full path: C:\Users\<username>\AppData\Roaming\FreeCAD\Mod\) * |
| Linux | v0.20+: ~/.local/share/FreeCAD/Mod/ v0.19 & older: ~/.FreeCAD/Mod/ |
| macOS | /Users/<username>/Library/Application Support/FreeCAD/Mod/ |
- Linux (Snap/Flatpak): If you installed FreeCAD via a sandboxed package manager, the directory will be different:
- Snap:
~/snap/freecad/common/Mod/ - Flatpak:
~/.var/app/org.freecad.FreeCAD/data/FreeCAD/Mod/
- Snap:
If you aren't sure where your specific installation is looking for files, you can find the exact path directly inside FreeCAD:
- Open FreeCAD.
- In the Python Console (View > Panels > Python Console), type the following and press Enter:
App.getUserAppDataDir() - The output will be the parent directory of your
Modfolder.
freecad -M <path to MyAddon>See instructions here: https://freecad.github.io/Addon-Academy/
