What Is the FreeCAD user.cfg Configuration File?

The user.cfg file is the primary configuration file used by FreeCAD to store user-defined preferences, graphical interface layouts, and application settings. This article explains the core purpose of user.cfg, details where it is located across different operating systems, describes how it can be safely modified, and highlights its role in troubleshooting FreeCAD issues.

The Primary Role of user.cfg

FreeCAD is a highly modular open-source parametric 3D CAD program. To ensure that your workspace remains consistent between sessions, FreeCAD writes your custom settings to an XML-structured file named user.cfg. Every time you adjust a parameter in the preferences window, rearrange a toolbar, or install a workbench, those adjustments are recorded here.

Key components stored in user.cfg include:

  • Interface Layouts: Window positions, dockable panel placements, toolbar locations, and theme selections.
  • Application Preferences: Default unit systems (metric, imperial, etc.), background colors, navigation styles, and rendering options.
  • Workbench Configurations: Individual settings, tool visibility, and operational defaults for specific workbenches like PartDesign, Sketcher, or Draft.
  • Custom Shortcuts: User-defined keyboard shortcuts and mouse bindings.
  • Recent History: File history and recently used parameter presets.

File Location Across Operating Systems

FreeCAD creates and manages the user.cfg file within the user profile directory of the operating system:

  • Windows: C:\Users\<Username>\AppData\Roaming\FreeCAD\user.cfg
  • Linux: ~/.config/FreeCAD/user.cfg (or inside flatpak/snap container directories if installed via sandbox packages)
  • macOS: ~/Library/Preferences/FreeCAD/user.cfg or ~/Library/Application Support/FreeCAD/user.cfg

Editing and Managing user.cfg

While user.cfg can be opened and edited with any standard text editor, FreeCAD provides a built-in graphical interface called the Parameter Editor. You can access it directly inside FreeCAD by navigating to Tools > Edit parameters.... This tool organizes the XML nodes into an expandable tree, reducing the likelihood of formatting errors.

If you edit the file manually in an external text editor:

  1. Close FreeCAD completely first. FreeCAD overwrites user.cfg upon closing, which will overwrite any external changes made while the program is running.
  2. Maintain the XML syntax strictly, as an unclosed tag can corrupt the configuration.

Troubleshooting and Resetting FreeCAD

Corrupted configurations can lead to interface glitches, crashing on startup, or unexpected tool behavior. Because user.cfg contains all user modifications, deleting or renaming the file is the standard method for resetting FreeCAD to its factory default state.

When FreeCAD starts and cannot locate user.cfg, it automatically generates a fresh, default version. Renaming the file to user.cfg.bak allows you to revert changes safely if resetting does not resolve the issue. Additionally, backing up this file enables you to migrate your exact UI layouts and shortcuts across multiple machines.