ChimeraX home icon

ChimeraX Troubleshooting

Solutions for common ChimeraX problems:

  1. ChimeraX won't start on Windows.
  2. ChimeraX crashes on Mac.

Problems


  1. ChimeraX won't start on Windows.

    Broken graphics driver. The most common reason ChimeraX fails to start is your system graphics driver updated and is broken now. The fix is to install a working graphics driver (either a newer version or older version).

    Corrupted preference settings. Another rare possibility is that the saved ChimeraX preferences got corrupted somehow. These are saved in directory

    	C:\Users\your-user-name\AppData\Local\UCSF\ChimeraX
    

    and you could rename that directory so that ChimeraX creates a new one to see if that is the problem.

    Start in debug mode. One last thing you could try to see if there is an error message is to start ChimeraX in debug mode by right clicking the desktop icon, choose Properties, and change Target from

    	"C:\Program Files\ChimeraX 1.3\bin\ChimeraX.exe"
    
    to
    	"C:\Program Files\ChimeraX 1.3\bin\ChimeraX-console.exe" --debug
    

    Then when you double click that icon it will bring up a console that logs ChimeraX messages as it starts up and you may see an error that explains what went wrong.


  2. ChimeraX crashes on Mac.

    Graphics driver crash. The most common cause of Mac crashes is because of unstable Apple OpenGL graphics drivers.

    We suggest you press the "Report to Apple" button when ChimeraX crashes to remind Apple that users still want support for OpenGL. There is nothing ChimeraX can do to prevent crashes from bugs in Apple's graphics drivers. Most ChimeraX crashes on Mac computers are in Apple's graphics drivers.

    Apple deprecated OpenGL graphics: Apple's OpenGL graphics drivers in macOS frequently crash. Apple deprecated the community standard OpenGL 3D graphics library in 2018 in favor of their proprietary Metal graphics library. Even prior to that Apple OpenGL version was 4.1 which dates from 2010. Crashes in macOS versions 10.14 (Mojave), 10.15 (Catalina), and 11 (Big Sur) are all common.

    No graphics crashes on new Apple M1 computers: No ChimeraX graphics crashes have been reported on Apple's new Mac computers based on the M1 graphics processor which was released a year ago (November 2020). Also the graphics performance on the new Apple M1 computers is good, with the M1 Pro graphics (Nov 2021) about as fast as a top-of-the-line 2019 Mac Book Pro with discrete AMD Vega 20 graphics (details).

    Windows and Linux have stable graphics: ChimeraX uses OpenGL so that it can run on Windows, Linux and macOS. Over a hundred ChimeraX crashes in the macOS OpenGL graphics driver have been reported, while almost no graphics crashes are reported on Windows and Linux which provide reliable OpenGL drivers.