To start the Preferences editor select the Edit → Preferences... option from the menu. On macOS the Preferences... option appears in the FreeCAD menu instead (this is the default place for preferences on the Mac).
FreeCAD uses a workbench concept, where each workbench is responsible for specific tasks and functions. A workbench can have its own preferences. These will only appear in the Preferences editor, usually in a dedicated section, if the workbench has been loaded in the current FreeCAD session. Some workbenches add support for specific import and export formats. If there are any related preferences they will appear on one or more additional tabs in the Import-Export section of the Preferences editor.
To preserve resources, FreeCAD does not automatically load all available workbenches. See Workbenches for more information. For a list of workbench related preferences see Workbench related preferences.
If no workbench is loaded, six sections appear in the Preferences editor: General, Display, Workbenches, Python, Addon Manager and Import-Export. Any workbenches that have been loaded, and have their own preferences, will appear below these.
Please note that pressing the Reset button in the lower left corner of the Preferences dialog will reset all FreeCAD preferences to their default values.
Some advanced preferences can only be changed in the Parameter editor. The Fine-tuning page lists some of them.
This preferences section has six standard tabs: General, Document, Selection, Cache, Notification Area and Report view. A seventh tab, Help, is added if the Help Addon is available. This addon can be installed via the Addon Manager.
On the General tab you can specify the following:
|Language||Specifies the language of the FreeCAD user interface.|
|Unit system||Specifies the unit system to be used for all parts of FreeCAD.|
|Number of decimals||The number of decimals that should be shown for numbers and dimensions.|
|Number format introduced in version 0.20||Specifies the number format. The options are:
|Substitute decimal separator introduced in version 0.20||If checked, the numerical keypad decimal separator will be substituted with the separator defined by the Number format setting. introduced in version 0.21: Notice that if this preference is enabled, using the numerical keypad decimal separator will always print a dot/period in the Python console and the Macro editor.|
|Style sheet||Specifies a style sheet. Style sheets define how the user interface of FreeCAD looks. For technical details about style sheets see themes.|
|Size of toolbar icons||Specifies the size of the toolbar icons. The options are:
|Tree view mode||Defines how the tree view is shown in the user interface (restart required). The options are:
|Size of recent file list||Specifies how many files should be listed in the recent files list.|
|Enable tiled background||If checked, the background of FreeCAD's main window will by default consist of tiles of this image:
This option only has an effect if no Style sheet is selected.
The image can be changed by adding the folders Gui/Images in the folder:
%APPDATA%/FreeCAD (on Windows),
$HOME/.FreeCAD (on Linux) or
$HOME/Library/Preferences/FreeCAD (on macOS).
Place a file named background.png in the Images folder, and uncheck/check this option to see the changed file.
|Enable splash screen at start up||If checked, a splash screen is shown when starting FreeCAD.
The splash screen image can be changed by placing a file named splash_image.png in the Images folder already mentioned under Enable tiled background.
|Enable cursor blinking||If checked the text cursor in the Python console and the Macro editor will blink.|
|Preference packs introduced in version 0.20||Lists the available preference packs and also allows you to import, save, manage and revert them.|
On the Document tab you can specify the following:
|Create new document at start up||If checked, FreeCAD will create a new document when started.|
|Document save compression level||Specifies the compression level for FCStd files. FCStd files are ZIP-compressed files. Therefore you can rename their suffix .FCStd to .zip and open them with a ZIP archive program.|
|Using Undo/Redo on documents||If checked, all changes in documents are stored so that they can be undone/redone.|
|Maximum Undo/Redo steps||Specifies how many Undo/Redo steps should be recorded.|
|Allow aborting recomputation||If checked, recomputations can be aborted by pressing Esc. This may slightly increase the recomputation time.|
|Run AutoRecovery at startup||If there is a recovery file available FreeCAD will automatically run a file recovery when it is started. This way files can be restored if a crash occurred.|
|Save AutoRecovery information every||Specifies how often a recovery file is written.|
|Save thumbnail into project file when saving document||If checked, a thumbnail will be stored when the document is saved. The thumbnail will for example be shown in the list of recent files in the Start Workbench. It is possible to select a Size between 128×128 and 512×512 pixels for the thumbnail. Common sizes are powers of two: 128, 256, 512.|
|Add the program logo to the generated thumbnail||If checked, the FreeCAD program logo will be added to the thumbnail.|
|Maximum number of backup files to keep when resaving document||If checked, backup files will be kept when saving the document. You can specify the number of backup files to keep. Backup files are previously saved versions of the document. The first backup file will have the file suffix .FCStd1, the second .FCStd2 and so on.|
|Use date and FCBak extension||If checked, backup files will get the extension .FCbak and their file names get a date suffix according to the specified Date format. For a description of the date format see Date & time formats cheatsheet.
With the default settings a backup file will for example get this name TD-Cube.20200315-215654.FCBak (original filename is TD-Cube.FCStd).
|Allow duplicate object labels in one document||If checked, objects can have the same label.|
|Disable partial loading of external linked objects||If partial loading of external linked objects is enabled, only the referenced objects and their dependencies will be loaded when the linked document is auto opened together with the main document. Such a partially loaded document cannot be edited. Double click the document icon in the tree view to reload it in full. A more detailed explanation of this feature can be found on the Assembly3 documentation page.|
|Author name||All created documents will get the specified author name. Keep the author field blank if you do not want to include this information. If the option Set on save is checked, the field Last modified by will be set to the specified author when saving the file. This field can be viewed using the File → Project information menu option.|
|Company||All created documents will get the specified company name.|
|Default license||Specifies the license for new documents. For predefined licenses the License URL will automatically be set accordingly. Select Other for a custom license.|
|License URL||Specifies an URL describing the license selected in Default license.|
On the Selection tab you can specify the following:
|Auto switch to the 3D view containing the selected item||Enables the Tree view SyncView mode.|
|Auto expand tree item when the corresponding object is selected in 3D view||Enables the Tree view SyncSelection mode.|
|Preselect the object in 3D view when mouse over the tree item||Enables the Tree view PreSelection mode.|
|Record selection in tree view in order to go back/forward using navigation button||Enables the Tree view RecordSelection mode.|
|Add checkboxes for selection in document tree||Each Tree view item will get a checkbox. This is for example useful for selecting multiple items on a touchscreen.|
These preferences are related to the cache directory where FreeCAD stores temporary files.
On the Cache tab (introduced in version 0.20) you can specify the following:
|Location||Specifies the path of the cache directory.|
|Check periodically at program start||Controls the frequency with which the directory size is checked. The options are:
|Cache size limit||Specifies the maximum size of the directory. You will be notified if a check is performed and the size exceeds this value. The options are:
|Current cache size||Shows the current size of the directory, if available. Press the Check now... button to update the value.|
These preferences control the Notification Area and its notifications.
On the Notification Area tab (introduced in version 0.21) you can specify the following:
|Enable Notification Area||If checked, the Notification Area will appear in the status bar.|
|Enable non-intrusive notifications||If checked, non-intrusive notifications will appear next to the Notification Area in the status bar.|
|Errors||If checked, errors will appear in the Notification Area.|
|Warnings||If checked, warnings will appear in the Notification Area.|
|Maximum Duration||Maximum duration during which notifications are shown (unless mouse buttons are clicked).|
|Minimum Duration||Minimum duration (idem).|
|Maximum Number of Notifications||Maximum number of notifications shown simultaneously.|
|Notification width||Width of the Notification Area in pixels.|
|Hide when other window is activated||If checked, open notifications will disappear when another window is activated.|
|Do not show when inactive||If checked, notifications will not appear if the FreeCAD window is not the active window.|
|Maximum Messages (0 = no limit)||The maximum number of messages kept in the list. Set to 0 for no limit.|
|Auto-remove User Notifications||If checked, notifications will be removed from the message list when the Maximum Duration has elapsed.|
These preferences control the behavior of the Report view. This panel can be opened using the View → Panels → Report view menu option.
On the Report view tab you can specify the following:
|Record normal messages||If checked, normal messages will be recorded. They will be displayed in the Report view with the color set in Normal messages.|
|Record log messages||If checked, log messages will be recorded. They will be displayed in the Report view with the color set in Log messages.|
|Record warnings||If checked, warnings will be recorded. They will be displayed in the Report view with the color set in Warnings.|
|Record error messages||If checked, error messages will be recorded. They will be displayed in the Report view with the color set in Errors.|
|Show report view on error||If checked, the Report view will be shown automatically when an error is recorded.|
|Show report view on warning||If checked, the Report view will be shown automatically when a warning is recorded.|
|Show report view on normal message||If checked, the Report view will be shown automatically when a normal message is recorded.|
|Show report view on log message||If checked, the Report view will be shown automatically when a log message is recorded.|
|Include a timecode for each entry||If checked, each message and warning will receive a timecode.|
|Normal messages||Specifies the font color for normal messages.|
|Log messages||Specifies the font color for log messages.|
|Warnings||Specifies the font color for warning messages.|
|Errors||Specifies the font color for error messages.|
|Redirect internal Python output to report view||If checked, internal Python output will be redirected from the Python console to the Report view.|
|Redirect internal Python errors to report view||If checked, internal Python error messages will be redirected from the Python console to the Report view.|
This tab is only available if the Help Addon has been installed.
On the Help tab you can specify the following:
|Help location||Specifies the location of the Help files. The options are:
|Display||Specifies where the documentation should be displayed. The options are:
|Custom stylesheet||Specifies an optional custom stylesheet. Not used for the Wiki URL.|
This preferences section has three standard tabs: 3D View, Navigation and Colors. A fourth tab, Mesh view, is added if the Mesh Workbench has been loaded.
On the 3D View tab you can specify the following:
|Show coordinate system in the corner||If checked, the main coordinate system will be shown in the lower right corner of the 3D view.
The Relative size (introduced in version 0.20) defines the size of the representation as a percentage of the view size (the minimum of its height and width).
|Show axis cross by default||If checked, the axis cross will be shown by default in the 3D view.|
|Show counter of frames per second||If checked, the time needed for the last operation and the resulting frame rate will be shown in the lower left corner of the 3D view.|
|Use software OpenGL||If checked, OpenGL will use the CPU instead of the GPU. This option is useful for troubleshooting graphics card and driver problems. Changing this option requires a restart of the application.|
|Use OpenGL VBO (Vertex Buffer Object)||If checked, Vertex Buffer Objects (VBO) will be used. A VBO is an OpenGL feature that provides methods for uploading vertex data (position, normal vector, color, etc.) to the graphics card. VBOs offer substantial performance gains because the data resides in the graphics memory rather than the system memory and so it can be rendered directly by the GPU. For more background info see Understanding OpenGL Objects.|
|Render Cache||"Render Cache" or "Render Acceleration" is explained in more detail in FreeCAD assembly3 render-caching. The options are:
|Anti-Aliasing||Specifies if and what type of multisample anti-aliasing is used|
|Transparent objects||Specifies the render type of transparent objects. The options are:
|Marker size||Specifies the size of vertices (points) in the Sketcher Workbench. The clickable area of points can be additionally enlarged by increasing the Pick radius.|
|Pick radius (px)||Sets the area for picking elements in the 3D view. Larger value makes it easier to pick things, but can make some small features impossible to select.|
|Eye to eye distance for stereo modes||Specifies the eye-to-eye distance used for stereo projections. The specified value is a factor that will be multiplied with the bounding box size of the 3D object that is currently displayed.|
|Backlight color||If checked, backlight is enabled with the defined color. Backlight is used for rendering the back sides of faces. Usually, you don't see them in solids, unless you slice one with a clipping plane, or if the faces aren't oriented correctly. It is only used for objects whose Lighting property (on the View tab) is set to One side. If disabled, the back side of the faces of those objects will be black.
The related Intensity setting specifies the intensity of the backlight.
|Camera type||Specifies the camera projection type. The options are:
On the Navigation tab you can specify the following:
|Navigation cube||If checked, the Navigation cube will be shown in the 3D view.
Steps by turn defines the number of steps required for a full rotation when using the Navigation cube rotation arrows.
If Rotate to nearest is checked, the 3D view is rotated to the nearest most logical position, based on the current orientation of the cube, when a cube face is clicked. Else clicking a face will always result in the same rotation. introduced in version 0.20
Cube size defines the size of the cube. introduced in version 0.20
Color sets the base color for all elements. introduced in version 0.21
Corner defines where the Navigation cube is displayed in the 3D view. The options are:
Font name specifies the font used for the cube's texts. introduced in version 0.21
Font size sets the size of the font used for the cube's texts. introduced in version 0.21
|3D Navigation||Specifies a mouse navigation style. To see the details of each style, select it and then press the Mouse... button.|
|Orbit style||Specifies the rotation orbit style used when in rotation mode. The options are:
|Rotation mode||Defines the rotation center. The options are:
|Default camera orientation||Specifies the camera orientation for new documents. This setting is also used by the Std ViewHome command.|
|Camera zoom||Affects the initial camera zoom level for new documents. The value you set is the diameter of a sphere that fits in 3D view. The default is 100 mm. It also sets the initial size of origin features (base planes in new PartDesign Bodies and Std Parts).|
|Enable animation||If checked, and 3D Navigation is set to CAD, rotations can be animated. If the mouse is moved while the scroll wheel and the right mouse button are pressed, the view is rotated. If one keeps the mouse moving while releasing the right mouse button, the rotation will continue. To end this animation left-click with the mouse.|
|Zoom at cursor||If checked, zoom operations will be performed at the position of the mouse pointer. Otherwise zoom operations will be performed at the center of the current view. The Zoom step defines how much will be zoomed. A zoom step of 1 means a factor of 7.5 for every zoom step.|
|Invert zoom||If checked, the direction of zoom operations will be inverted.|
|Disable touchscreen tilt gesture||If checked, and 3D Navigation is set to Gesture, the tilting gesture will be disabled for pinch-zooming (two-finger zooming).|
On the Colors tab you can specify the following:
|Enable preselection highlighting||If checked, preselection is turned on and the specified color will be used for it. Preselection means that for example edges of objects will be highlighted while hovering over them with the mouse to indicate they can be selected.|
|Enable selection highlighting||If checked, selection highlighting is turned on and the specified color will be used for it.|
|Simple color||If selected, the background of the 3D view will have the specified color.|
|Linear gradient||If selected, the background of the 3D view will have a vertical color gradient defined by the specified Top and Bottom colors. if enabled, a Middle color can also be specified. Press the button (introduced in version 0.21) to switch the top and bottom colors.|
|Radial gradient introduced in version 0.21||If selected, the background of the 3D view will have a radial color gradient defined by the specified Central and End colors. if enabled, a Midway color can also be specified. Press the button to switch the central and end colors.|
|Object being edited||Specifies the background color for objects in the tree view that are currently edited.|
|Active container||Specifies the background color for active containers in the tree view. For example an active PartDesign Body will get this color.|
This tab is only available if the Mesh Workbench has been loaded.
On the Mesh view tab you can specify the following:
|Default mesh color||Specifies the default face color.|
|Default line color||Specifies the default line color.|
|Mesh transparency||Specifies the default mesh transparency.|
|Line transparency||Specifies the default line transparency.|
|Two-side rendering||If checked, the default value for the ViewLighting property is |
|Show bounding-box for highlighted or selected meshes||If checked, the default value for the ViewSelection Style property is |
|Define normal per vertex||If checked, Phong shading is used, otherwise flat shading. Shading defines the appearance of surfaces. With flat shading the surface normals are not defined per vertex. This leads to an unrealistic appearance for curved surfaces. While Phong shading leads to a more realistic, smoother appearance.|
|Crease angle||The crease angle is a threshold angle between two faces. It can only be set if the option Define normal per vertex is used.
This preferences section has a single tab: Available Workbenches.
These preferences control workbench loading.
On the Available Workbenches tab you can specify the following:
|Workbench list||The list displays all installed workbenches. introduced in version 0.21: The list can be reordered by drag and drop. The order of the list also determines the order of the Workbench selector.
|Start up workbench||The workbench that is activated when FreeCAD starts.|
|Workbench selector position introduced in version 0.21||Defines where the Workbench selector appears. The options are:
|Remember active workbench by tab||If checked, FreeCAD will remember and restore the workbench that was active for each tab in the Main view area.|
This preferences section (introduced in version 0.21) has three tabs: Macro, Python console and Editor.
On the Macro tab you can specify the following:
|Run macros in local environment||If checked, variables defined by macros are created as local variables, otherwise as global Python variables.|
|Macro path||Specifies the path for macro files.|
|Record GUI commands||If checked, recorded macros will also contain user interface commands.|
|Record as comment||If checked, recorded macros will also contain user interface commands, but as comments. This is useful if you don't want to execute these commands when running the macro, but do want to see what has been done while recording.|
|Show script commands in python console||If checked, the commands executed by macro scripts are shown in the Python console. This console can be opened using the View → Panels → Python console menu option.|
|Size of recent macro list||Controls the number of recent macros to display in the menu.|
|Shortcut count||Controls the number of recent macros that get dynamically assigned shortcuts.|
|Keyboard Modifiers||Controls which keyboard modifiers are used for the shortcuts, example Ctrl+Shift+ creates shortcuts in the form of Ctrl+Shift+1, Ctrl+Shift+2, etc.|
These preferences control the behavior of the Python console. This console can be opened using the View → Panels → Python console menu option.
Note that the color and font settings for the console are defined on the Editor tab.
On the Python console tab (introduced in version 0.20) you can specify the following:
|Enable word wrap||If checked, words will be wrapped if they exceed the available horizontal space in the console.|
|Enable block cursor||If checked, the cursor will have a block shape.|
|Save history||If checked, Python history is saved across sessions.|
These preferences control the behavior of the Macro editor. This editor can be opened using the Macro → Macros... → Edit or Create menu option.
The color and font settings are also used by the Python console.
On the Editor tab you can specify the following:
|Enable line numbers||If checked, the code lines will be numbered.|
|Enable block cursor||If checked, the cursor will have a block shape.|
|Tab size||Specifies the tabulator raster (how many spaces). If it is for example set to 6, pressing Tab will jump to character 7 or 13 or 19 etc., depending on the current cursor position. This setting is only used if Keep tabs is selected.|
|Indent size||Specifies how many spaces will be inserted when pressing Tab. This setting is only used if Insert spaces is selected.|
|Keep tabs||If selected, pressing Tab will insert a tabulator with the raster defined by Tab size.|
|Insert spaces||If selected, pressing Tab will insert the amount of spaces defined by Indent size.|
|Display Items||Specifies the code type the color and font settings will be applied to. The result can be checked in the Preview field.|
|Family||Specifies the font family that should be used for the selected code type.|
|Size||Specifies the font size that should be used for the selected code type.|
|Color||Specifies the color that should be used for the selected code type.|
This preferences section has a single tab: Addon manager options.
Addon manager options
These preferences control the behavior of the Addon manager.
On the Addon manager options tab (introduced in version 0.20) you can specify the following:
|Automatically check for updates at start (requires git)||If checked, the Addon manager will check for updates when it is launched. Git must be installed for this to work.|
|Download Macro metadata (approximately 10MB)||If checked, macro metadata is downloaded for display in the Addon manager's main addon listing. This data is cached locally.|
|Cache update frequency||Controls the frequency with which the locally cached addon availability and metadata information is updated. The options are:
|Hide Addons marked Python 2 Only||If checked, addons marked as "Python 2 Only" are not included in the listing. These addons are unlikely to work in the current FreeCAD version.|
|Hide Addons marked Obsolete||If checked, addons marked as "Obsolete" are not included in the listing.|
|Hide Addons that require a newer version of FreeCAD||If checked, addons that require a newer FreeCAD version are not included in the listing.|
|Custom repositories||Custom repositories can be specified here.
To add a repository press the button. Both the Repository URL and the Branch, typically
To remove a repository select it in the list and press the button. introduced in version 0.21
|Proxy||The Addon manager includes experimental support for proxies requiring authentication, set up as user-defined proxies.|
|Python executable (optional)||The Addon manager attempts to determine the Python executable that should be used for the automatic pip-based installation of Python dependencies. To override this selection, the path to the executable can be set here.|
|git executable (optional)||The Addon manager attempts to determine the git executable. To override this selection, the path to the executable can be set here. introduced in version 0.21|
|Show option to change branches (requires git)||If checked, the Addon manager provides an interface on the addon's details screen that allows switching which git branch is currently checked out. This is intended for advanced users only, as it is possible that a non-primary-branch version of an addon may result in instability and compatibility issues. Git must be installed for this to work. Use with caution.|
|Disable git (fall back to ZIP downloads only)||If checked, git downloads are disabled. introduced in version 0.21|
|Addon developer mode||If checked, Addon manager options intended for developers of addons are activated. introduced in version 0.21|
The Import-Export preferences affect how files are imported and exported. They are described on the Import Export Preferences page.
Preferences for the built-in workbenches are linked below. These links are also listed in Category:Preferences. Some workbenches have no preferences.
- Arch Preferences
- Draft Preferences
- FEM Preferences
- Inspection Preferences (none)
- Mesh Design Preferences
- OpenSCAD Preferences
- Part Preferences: the Part workbench also uses the PartDesign Preferences
- PartDesign Preferences
- Path Preferences
- Points Preferences (none)
- Raytracing Preferences
- Reverse Engineering Preferences (none)
- Robot Preferences (none)
- Sketcher Preferences
- Spreadsheet Preferences
- Start Preferences
- Surface Preferences (none)
- TechDraw Preferences
- Test Framework Preferences (none)
- Web Preferences (none)
See also: FreeCAD Scripting Basics.
For a scripting example see Std DlgParameter.
- Getting started
- Installation: Download, Windows, Linux, Mac, Additional components, Docker, AppImage, Ubuntu Snap
- Basics: About FreeCAD, Interface, Mouse navigation, Selection methods, Object name, Preferences, Workbenches, Document structure, Properties, Help FreeCAD, Donate
- Help: Tutorials, Video tutorials
- Workbenches: Std Base, Arch, Draft, FEM, Inspection, Mesh, OpenSCAD, Part, PartDesign, Path, Points, Reverse Engineering, Robot, Sketcher, Spreadsheet, Start, Surface, TechDraw, Test Framework, Web
- Hubs: User hub, Power users hub, Developer hub