FreeCAD: How to fix if FreeCAD fails to start

FreeCAD 0.19

This is a list to be checked when FreeCAD can not start after installation.

  1. Check username and install path

    If non-ascii character (i.e. Non-alphanumeric characters) exists in OS username or FreeCAD installation path ("C:\Program Files\FreeCAD $(version number)\bin\FreeCAD" in default on Windows), FreeCAD may fail to start. Make sure that your username and installation is only make from ascii character and if it has non-ascii character, change the name or path.

    On Windows, older username may remains in application data folder name or other after username changing. In such case, you should make new user on Windows and use FreeCAD as the user.

  2. Check installer

    Official FreeCAD can be downloaded from GitHub (FreeCAD releases page).

    For example, installer file name for each OS in version 0.19.1 is as following.

    • Windows: FreeCAD-0.19.1.a88db11-WIN-x64-installer-1.exe
    • macOS: FreeCAD_0.19-24276-macOS-x86_64-conda.dmg
    • Linux: FreeCAD_0.19-24276-Linux-Conda_glibc2.12-x86_64.AppImage

    Download the installer again to make sure the installer is not broken and make sure it is the same size as the one previously downloaded. On Windows, you can check the file size by right-click the file.

    In some version of FreeCAD, SHA256 file hash value is provided. For example, you can get the hash value for 64 bit Windows from a file "FreeCAD-0.19.1.a88db11-WIN-x64-installer-1.exe-SHA256.txt". You can get the actual hash value with following command on Windows and make sure that is same as provided value.

    >"certutil -hashfile (FreeCAD installation path)\FreeCAD-0.19.1.a88db11-WIN-x64-installer-1.exe SHA256
  3. Check graphics cards

    • The system must support OpenGL for FreeCAD working (almost all modern systems support OpenGL).

    • If it is possible, install software that uses OpenGL, such as Blender, and check if it can start normally. If not, there can be a problem with the graphics card.

    • Make sure that the combination of graphics cards and installed driver is correct.

      It is reported in FreeCAD official page that ATI driver was installed for Intel onboard graphics card and FreeCAD crashed. If it is worng combination, uninstall the wrong driver and install FreeCAD again.

    • If it is possible, update your graphics cards driver to the latest version. Graphics card drivers are distributed on the pages of each manufacturer (NVIDIA, ATI, etc.).

  4. Check libraries

    If the system is inconsistent, FreeCAD may not be able to start because it cannot find the correct library.

    It is reported in FreeCAD official page that FreeCAD crash if GUI framework Qt3 or Qt4 is installed in an inappropriate way. In such case, FreeCAD may start normally after uninstalling the software that uses Qt3 or Qt4.

  5. Check FreeCAD configuration file

    If the FreeCAD configuration file is damaged, FreeCAD may crash. In that case, delete the corrupted FreeCAD configuration file as follows:

    • On Windows: Delete "%APPDATA%\FreeCAD\system.cfg"
    • On Mac or Linux: Delete "$HOME/.FreeCAD"

    After deleting the file, Check if FreeCAD starts.

  6. If the problem still exists...

    Start FreeCAD by command line with "--write-log" option to write log file (using command-prompt on Window, terminal on MacOS or Linux). And post the log file and a question about the problem to the FreeCAD forum.

    • Command line example (On Windows, FreeCAD 0.19)

      >"C:\Program Files\FreeCAD 0.19\bin\FreeCAD" --write-log
    • Log file path

      • On Windows: %APPDATA%\FreeCAD\FreeCAD.log
      • On Mac or Linux: $HOME/.FreeCAD/FreeCAD.log
    • FreeCAD Forum