ChimeraX home icon

ChimeraX Troubleshooting

Solutions for common ChimeraX problems:

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.


ChimeraX crashes on Mac


Mac Intel or AMD graphics driver crash. The most common cause of Mac crashes is because of unstable Apple OpenGL graphics drivers. 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.

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).

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.


Mac display configuration crash. On Mac computers ChimeraX sometimes crashes when waking from sleep or disconnecting or connecting an external display. This is a bug in the Qt window toolkit (versions 6.6 and 6.7) used by ChimeraX. We have not been able to reproduce this crash although it has been reported 50 times. We update ChimeraX daily builds when new Qt toolkit versions are released and will report here if an update fixes this crash.