How to Share Custom Python Macros in FreeCAD

Sharing custom Python macros with the FreeCAD community ensures your tools reach other designers, receive peer feedback, and help expand the software's open-source ecosystem. The most effective way to distribute a macro is through the official FreeCAD Addon Manager via the community macro repository, supplemented by documentation on the FreeCAD Wiki and discussion on the official user forums.

1. The Official FreeCAD Addon Manager Repository

The standard and most accessible method for end-users to install your script is directly inside FreeCAD using the built-in Addon Manager (Tools > Addon Manager). For your macro to appear in this list, it must be added to the centralized FreeCAD-macros repository on GitHub.

To submit your macro:

  • Fork the Repository: Create a fork of the official FreeCAD/FreeCAD-macros GitHub repository.
  • Format the File: Ensure your macro file uses the .FCMacro file extension instead of .py.
  • Add an Icon: Create a 64x64 pixel SVG icon with the same base name as your macro (e.g., MyMacro.FCMacro and MyMacro.svg) so it displays properly in the interface.
  • Submit a Pull Request: Commit your files to your fork and open a Pull Request (PR) against the main repository. Once reviewed and merged by the maintainers, it will automatically populate in the Addon Manager for all FreeCAD users.

2. Include Required Macro Metadata

For the Addon Manager and users to properly understand your macro, include standardized metadata in the header comments of your Python code. Place this block at the very top of your .FCMacro file:

__Name__ = "Macro Name"
__Comment__ = "A brief explanation of what the macro accomplishes"
__Author__ = "Your Name"
__Version__ = "1.0.0"
__Date__ = "YYYY-MM-DD"
__License__ = "LGPL-2.1-or-later"
__Web__ = "https://wiki.freecad.org/Macro_Your_Macro_Name"
__Wiki__ = "https://wiki.freecad.org/Macro_Your_Macro_Name"
__Icon__ = "MyMacro.svg"
__Help__ = "Instructions on how to execute or configure the macro"
__Status__ = "Stable"
__Requires__ = "FreeCAD >= 0.20"

This metadata allows the Addon Manager to filter by version requirements, link documentation, and display licensing information clearly.

3. Document on the FreeCAD Wiki

The FreeCAD community relies heavily on its wiki for instructions and troubleshooting. Creating a dedicated wiki page for your macro provides users with detailed usage steps, animated examples, and compatibility notes.

  • Request editor access on the FreeCAD Wiki via the forums if you do not already have an account.
  • Use the standard macro template by naming your page Macro_YourMacroName.
  • Include installation steps, step-by-step usage instructions, known limitations, and a changelog.

4. Announce on the FreeCAD Forum

Before or alongside submitting to the Addon Manager, post your macro in the Python Scripting and Macros subforum on the official FreeCAD forum.

Forum threads allow you to:

  • Test pre-release versions across different operating systems (Windows, macOS, Linux).
  • Solicit feedback on edge cases, performance, and user interface design.
  • Announce updates, bug fixes, and feature additions to active community members.