Version Migration

Introduction

Starting in version 1.1 FreeCAD natively supports versioned configuration and app-data subdirectories. If there is an existing configuration file when a new version is first started, a screen appears offering to either migrate to a versioned structure by copying an existing configuration, to continue using a "shared" configuration from a previous version, or to start with a new default configuration.

Available migration options

Migrate to a versioned configuration

The default, and recommended, option is to migrate an existing configuration into a new one for the new version of FreeCAD. The consequence is that all of the installed addons, config files, and other user data is duplicated into a new directory for the new version. This means that if an older version of FreeCAD is launched it will be able to use the older configuration and addons, preserving compatibility and preventing any data loss or potential unexpected behavior if an old version tries to load new configuration options, updated addons, etc.

Share configurations

Users with very large app data directories (for example because the Parts Library is installed) may not wish to duplicate all data and may choose to continue to use the last-found configuration folder (for versions prior to 1.1 this is an unversioned directory). This runs the risk that a new configuration or addon will prevent an older version of FreeCAD from loading correctly.

Start with a new default configuration

This option creates a new versioned configuration directory, but does not copy anything into it, starting the new installation with fresh "factory default" settings.

Information for addon authors

If your addon relied on recording/storing the absolute location of its files (rather than their location relative to userAppDataDir or configDir), you will need to detect that the files have been migrated and update your stored configuration variables. Several Python methods are exposed to assist in this process, most importantly FreeCAD.ApplicationDirectories.versionStringForPath(major, minor) and FreeCAD.ApplicationDirectories.versionStringForPath.usingCurrentVersionConfig(pathToCheck).