[Closed] [GUIDE] Troubleshooting eGPUs on macOS
Troubleshooting eGPUs on macOS
eGPU support has gained a ton of traction in the past year, but we are not out of the woods yet. It's always a challenge to create perfect hacks - there aren't many out there. Thus we must rely on good ol' troubleshooting to see the light. This extensive guide is aimed at all eGPU users using macOS 10.13.4 or later.
Getting your hardware right is half the battle. Prepare well.
Ever in doubt if your eGPU is working? Find out for once and for all.
Is macOS deceiving you? Find out here.
Something's not right? No problemo.
An essential toolkit for the initiated.
Is your mac in a pinch? We've all been there. Let's get down to business.
Find out potential ways to resolve unexpected eGPU performance.
Find out the tools at your disposal to manage eGPU support on your system, and more.
I don't want this thread to be about "... troubleshooting technique did not work ..." - its different for everyone. Instead, I want it to be about feedback and suggestions to this guide - like what I've missed, some other neat tricks, and so on. A constructive thread, so to speak. I would kindly request eGPUio'rs to provide such feedback. For example, I have poor understanding of iMac performance and eGPU support - need more data about the tips and tricks involved there.
It is paramount to ensure your hardware configuration is optimal before anything else. Buyer’s Guide is here to help. You won’t find anything else as comprehensive as that, and being well-versed with it is half the battle. Some general considerations:
- Power: Ensure that the eGPU enclosure of your choice can sufficiently power your choice of GPU. At this time, Vega GPUs demand the most power, so be careful with them. GPUs not powered correctly may crash the system in the worst case.
- Thunderbolt: Use certified Thunderbolt 3 cables and adapters. Cables can affect bandwidth across the system and overall performance. If you are using a non-TB3 system, use certified adapters, such as Apple TB3 to TB2 adapter. Please note that TB2 & TB1 use the same cables and adapters - the difference is only in the protocol and ports on the systems.
Once you are certain that your hardware is functional and optimal, you can proceed with software modifications.
If you are already set up and running, but are not sure if your eGPU is being used, you have multiple ways to validate your eGPU activity:
- Activity Monitor: Use GPU History to see what’s going on with your GPUs. You can do this through Window > GPU History, or ⌘ + 4 after launching Activity Monitor.
- LuxMark: A useful OpenGL benchmarking tool that lists all available compute units. You can even benchmark one of your processors at a time.
- Geekbench: A household name in benchmarking that also lists available compute units for OpenCL & Metal benchmarking.
If your eGPU is visible and active in any of the above programs, it means that it has been initialized correctly.
Some users may believe that an eGPU is not working if About This Mac does not show it’s name in the Graphics section. This is incorrect. These are the facts:
- The graphics section typically shows GPUs being used on the primary display. Therefore, if your eGPU is solely accelerating your external monitor which hasn’t been set as the primary monitor, you won’t see it here.
- The section behaves somewhat differently if multiple GPUs are multiplexing on the same monitor. An example is when a mac is actively using its discrete GPU (high performance mode), where this section shows 2 GPUs.
- The About This Mac > Displays sections more accurately reveals GPUs and the displays they are connected to. Always use this for reference.
The most optimal configuration for eGPUs is to have a primary external display. Once you have your eGPU up and running:
- Go to System Preferences > Displays, and drag the white menu bar from the current primary display to your external display to set as primary.
- Check About This Mac - you will notice that the graphics section shows your eGPU name instead. Your internal GPUs are still there though, so don’t worry.
eGPUs & Internal Displays
By default, eGPUs will not accelerate a mac's internal display. Applications need to be designed to take advantage of external graphics on internal displays. For instance, DaVinci Resolve does so. It may be possible to force applications to use the eGPU using set-eGPU.sh, though the results may not always be satisfactory.
Understanding macOS Builds & Versions
Every macOS release, for the longest time, has had a version number and build identifier. Formerly known as Mac OS X, then just OS X, and now macOS, what didn't change were these numbers and identifiers.
Sample: 10.13.6 [17G65]
- 10.13.6 is the version number in the above sample. Think of it as MACOS_GEN.MAJOR.MINOR.
- MACOS_GEN = 10 -> we have been using macOS "X" since the start of the millennia
- MAJOR = 13 -> Yearly updates (since 7 -> 8) to macOS
- MINOR = 6 -> Refinement releases across the year
- Version numbers have corresponding build numbers, and they have quite an interesting relationship.
- 17G65 is the build identifier in the above sample. The breakdown is interesting: <MACOS_GEN><MINOR><BUILD_NO>
- MACOS_GEN = 17 -> correlates to 10.13 or High Sierra. They increase/decrease in tandem (Mojave -> 18 / 10.14)
- MINOR = G -> 6th letter -> 10.13.6
- BUILD_NO = 65 -> Think of it as an iteration on the goal build within Apple. Betas have smaller numbers, with yet another lower-case letter appended to it.
- Build numbers have other variations too. Security updates and some betas sometimes add an extra digit in the BUILD_NO (common in iOS betas -> appending 5 after minor release letter for instance).
Keep in mind that these build number relationships are not set in stone, and one may see some oddities (such as 10.13.6 for MBP 2018). This is just a primer on the general trends observed.
As mentioned earlier, eGPU support is not cut-and-dry yet - there are a variety of complications, but some have been dealt with. The rule of thumb is to read the entire post regarding scripts and software solutions before running the solution yourself. So before doing anything:
- Read the entire post regarding eGPU solutions and understand the disclaimer that goes along with them.
- Investigate the links of complications you think your setup might qualify for.
- eGPU solutions here have built-in mechanisms to recover from potential system damage or malfunction - know them well.
- Look at the Build Guides for information on your configuration.
An eGPU setup can be problematic based on:
- Mac Type: For example, macs with discrete NVIDIA GPUs have interesting edge cases.
- eGPU Brand: AMD and NVIDIA eGPUs behave very differently on different macs.
- Connectivity Type: In some cases, the cable quality, enclosure firmware, adapters, and thunderbolt versions play a significant role.
It is wiser to build known-working setups, which you may find in the Build Guides. If your system + eGPU configuration is not there, find the closest resembling build and ensure that you look at any edge cases involved. Also search the forums for dedicated threads if the issue is prevalent.
Before anything else, it is advised to disable System Integrity Protection at least during troubleshooting for optimality. Re-enable partially if desired once the problem is resolved.
Complications with NVIDIA eGPUs
There are many complications with NVIDIA eGPUs, given the lack of official support. Sometimes, the problem is obvious, but in many other cases, it can be non-trivial to comprehend. There are always a few things to try:
For Black Screens & Uninitialized eGPUs
- Cold Boots: Try booting with eGPU plugged in. This may sometimes resolve the problem. Also try disconnecting and re-connecting the external display to the eGPU.
- Log Outs: Try hot-plugging the eGPU, wait for eGPU initialization (~10s), and log out. You may see the external display functioning. Fiddle with the external monitor if needed. Tip: If both internal and external displays are black, you can log out by pressing ⌘+⇪+Q then return. If you have multiple external displays, and not all are accelerated/are black, try logging out/in multiple times.
- Mirroring: In specific cases, eGPUs may cause both the internal and external screens to render nothing. This might be because the displays are mirroring. In such a case, connect your external display directly to your mac, set it to disable mirroring, and then try using it with the eGPU again. If macOS remembers the display (ideally), it will default to extending instead of mirroring, and may resolve the issue.
For Live Connections/Disconnections
- Disconnections: Disconnecting NVIDIA eGPUs from the Safe eGPU Eject Menu is not supported and will crash your system. Future workarounds will remove this icon for NVIDIA eGPUs.
- Connections: Hot-plugs are supported depending on the system. For example, a mac with a built-in NVIDIA GPU may be unable to output to the external screen when hot-plugged. In such a case, follow the procedures outlined above for black screens.
For Boot Issues
- No Boot Sound + Failure: This means the system is failing the power-on-self-test (POST). Plug in the eGPU after this step is complete. An example combination is: NVIDIA 9xx or later eGPU + Mac with built-in NVIDIA GPU.
- Boot Failure with eGPU: This likely means an issue with NVIDIA Web Drivers. This will require a manual uninstallation of those drivers. See the Swiss Knife for more information on what to do.
For Rendering Issues
- No OpenCL/GL: A rare complication that arises on macs with built-in NVIDIA GPUs where eGPUs are unable to perform or compute using the OpenCL/GL API. The only way to resolve this was to use older NVIDIA Web Drivers. You can read about the experience here. With the new purge-nvda.sh update, it is possible to use newer drivers as well.
- Poor UI Performance: This may be an alternative complication to black screen problems. The steps recommended for black screens apply here as well.
Understanding NVIDIA Web Drivers
- NVIDIA have kept things simple - each build of macOS has its own compatible set of drivers. A one-to-one mapping. In our hacky world though, this doesn't really bode well in many cases, such as beta builds, or unique device builds.
- Patching an older driver for a newer minor build (A ->D, F -> G, etc.) or different build number (F100 -> F120, etc.) or a combination of the two is usually ok. Major build (17G -> 18A, etc.) changes will usually be fatal and can be considered to have a low chance of success. Of course, this is not definitive and depends per release.
A good list of problems and potential solutions with NVIDIA eGPUs has been compiled here.
Complications with AMD eGPUs
Although natively supported in macOS, AMD eGPUs have some interesting edge cases on macs, including problems with sleep and rendering. Fortunately, the experience is significantly smoother and simpler than NVIDIA eGPUs. Let's take a look:
- Sleep/Wake: This issue may occur on all macs running AMD eGPUs (native compatibility). The problem likely lies when macOS goes into deep sleep. One way to avoid this is to disable hibernation. This can be done with some of the eGPU solutions, but you can do so yourself using appropriate commands. FileVault may also need to be disabled.
- Black Screens: Typically only affects macs with built-in NVIDIA cards. They need to disable the NVIDIA GPU using purge-nvda. Doing so has it's own set of ramifications, but can be an appropriate tradeoff in most cases.
Using Thunderbolt Monitors with eGPUs
Unfortunately, GPUs do not have Thunderbolt/USB-C outputs for applicable monitors, and that means that these monitors need to be directly connected to Macs instead. In such a case, to accelerate the contents of the monitor using the eGPU:
- Headless Adapter: Use a headless adapter on the eGPU to simulate a monitor resolution similar to your TB monitor.
- Mirroring: Set the system to mirror displays, and for optimal performance, disable the internal display or enter clamshell mode if supported.
A new workaround, set-eGPU.sh, forces applications to use the eGPU, and can be an alternative to mirroring.
Support for thunderbolt monitors is still up in the air, and this technique may or may not work.
Bandwidth Issues With Thunderbolt 3
In some cases, TB3 eGPU setups may initialize at 20Gbps bandwidth for seemingly no clear reason. In such a case, the cable is most likely at fault. The most appropriate troubleshooting steps are to try different cables, as well as a different host system to eliminate other variables.
Issues with eGPU Connectivity & Previously Working Setups
Sometimes updating macOS to a new patch-supported version is not smooth, and previously working setups are broken. But in many cases, it is really the hardware that's at fault. Here are a few tips and tricks to understand what's going on:
- Regardless of any patch, a thunderbolt enclosure must power up if connected to macOS.
- If enclosure is not powering up, power cycle it, or disconnect everything for up to 10 minutes before re-trying.
- Monitor thunderbolt and kext activity in Console if all else fails:
- Ensure that any required eGPU patches are active.
- Launch Console from spotlight search.
- In the search bar, type in and filter for thunderbolt.
- Plug in eGPU.
- Look for thunderbolt activity. If there isn't a long list of messages, then the enclosure is not powered properly.
- Look for GPU-associated kext activity by filtering amd and nvda depending on eGPU.
- If you don't see activity, then either the GPU is not powered sufficiently or the connection is weak/loose.
- It may be helpful to disassemble/reassemble if applicable.
- macOS clean installs may resolve the issue.
- For the future, consider upgrading macOS without the eGPU plugged in during the process.
This section is for the initiated - a terminal command line galore to shoo away eGPU-related problems (or at least make an attempt), and for developers who want to further develop eGPU solutions. Let's check 'em out:
- Kext Unable To Load: A scenario where a customized kernel extension fails to load. You can resolve this by fixing it's permissions as follows -
sudo chown -R root:wheel <path to .kext file> sudo chmod -R 755 <path to .kext file>
- Verify If Kext Is Loadable: You can easily verify if a kernel extension is loadable -
sudo kextutil -n <path to .kext file>
- Rebuild Kext Cache: The recommended method to rebuild the kernel extension cache is to update the extensions folder and reboot -
sudo touch /System/Library/Extensions sudo reboot # or do sudo kextcache -i /
- Extract Packages Without Installing Them: Ever wanted to peak into a package, extract some part of its contents for partial use, and circumvent its restrictions? Then you're in for a treat with this hidden (literally) gem -
pkgutil --expand-full <path to .pkg file> <name of folder to create>
- Manage macOS Sleep Settings: For those who find the Energy settings lacking -
- Manage eGPUs in Terminal: You can actually deal with eGPUs programmatically -
- FileVault in Terminal: You can actually manage your FileVault settings more granularly using -
- Modify Property Lists (.plist) in Terminal: You need to see -
- Manual Web Driver Uninstallation: When you have no UI to help -
installer -target / -pkg /Library/PreferencePanes/NVIDIA\ Driver\ Manager.prefPane/Contents/MacOS/NVIDIA\ Web\ Driver Uninstaller.app/Contents/Resources/NVUninstall.pkg
- Manage NVRAM: Manage the non-volatile storage that provides essential boot data to the system -
- Disable GPU Muxing: When you don't want automatic graphics switching -
sudo nvram boot-args="agc=-1"
- Disabling GPUs: These preferences may render your system unbootable. Proceed with caution -
sudo nvram boot-args="-amd_no_dgpu_accel" # disable AMD GPU acceleration sudo nvram boot-args="nv_disable=1" # disable NVIDIA GPU (hard stops NVIDIA GPU) sudo nvram fa4ce28d-b62f-4c99-9cc3-6815686e30f9:gpu-power-prefs=%01%00%00%00 # switch mux to iGPU # -- Reverting mux sudo nvram fa4ce28d-b62f-4c99-9cc3-6815686e30f9:gpu-power-prefs=%00%00%00%00 # switch mux to dGPU
With all the precautions we take, sometimes software just doesn't behave as we want it to. In those tough times, one might lose hope, but never give up. In most cases, it is possible to recover the system without re-installing macOS or recovering from a Time Machine backup (which you better have - nonetheless). There are three primary means of recovering the system:
- macOS Recovery: Generally, a non-visible partition in macOS that can be used to recover potentially damaged systems as well as restore from Time Machine backups. You can easily boot into recovery using ⌘ + R. Internet recovery is also available, using ⌘ + ⌥ + R or ⌘ + ⌥ + ⇪ + R.
- macOS Single User Mode (SUM): This is a command-line interface enabled right before operating system boot begins. This is the mode to use when recovery is not possible and manual removal of items is required. Press ⌘ + S while booting.
- macOS Safe Boot: This allows the system to boot while loading only the necessary kernel extensions, clears system caches, and does not use the kernel cache. Press and hold shift while booting.
Issues After Kext Installations
If your system is unable to boot after recently installing kexts, such as NVIDIA Web Drivers or NVDAEGPUSupport, you can recover the system in two ways:
- Safe Mode: Boot into safe mode, delete the offending kexts, and reboot. In rare cases, it may not be possible to boot in safe mode. In such a case, use Single User Mode.
- Single User Mode: Boot into SUM and wait for the command line to initialize. Then follow #9 from Command Line Swiss Knife.
Issues After NVRAM Modifications
It is not uncommon for the system to fail boot if there's something shady going on in the NVRAM. You can resolve this in two ways:
- NVRAM Clear: Boot into Single User Mode, clear NVRAM, and reboot -
nvram -c reboot
- NVRAM Reset: Boot the system while pressing ⌘ + ⌥ + P + R until you hear the chime again. For systems that don't chime, watch for the screen to light up and turn off immediately, after which the keys can be released. This will reset System Integrity Protection as well (does not for NVRAM Clear).
Scripts such as purge-nvda modify the NVRAM for desired results. While the script has built-in recovery, in the rare scenario that it is not accessible, direct understanding of NVRAM might save you.
Sometimes, one may lose track of their current system configuration and the patches installed on the system. In such a scenario, the following steps are the most appropriate:
- Reinstall macOS: On top of your current installation, download and install the latest public release of macOS from the App Store. Doing so will likely eliminate any modified system files and settings, which are usually kext-related.
- Check /Library/Application Support: For installations from scripts. These can be safely removed if macOS has been installed on top of the existing installation, as the patches have been eliminated.
- Check Script Information: For some additional insight into where and what has been changed in the system. Since your system is clean, any lingering files can be safely eliminated. These may include daemons and other support files.
At this point, almost every user should be back into their OS regardless of the problem. However, in the rare case that even a reinstallation does not help, the only option is to restore from an untainted Time Machine backup.
While eGPUs may be working on your system, there can sometimes be interesting edge cases and complications with respect to its performance. You may see slower than expected numbers, lack of application support, preference of internal GPU instead of eGPU, and so on. Debugging performance is straightforward:
- Validate Expected Performance: It is important to understand how much performance the eGPU should be providing before deciding that a performance problem is affecting you. You can do this easily by checking the build guides using your eGPU and a host having the same thunderbolt interface. Please note that small variations are expected and rely on several other factors, predominantly CPUs.
- Validate Localization: Discern whether it is certain applications that aren't accelerating, or just all apps not doing so. Monitor eGPU activity in compute tasks vs. rendering tasks. Deduce what isn't working exactly and where.
- Check Applications: Many applications (such as Final Cut Pro) do not make use of the eGPU regardless of the configuration. It is essential to understand what apps work, and what don't. You will have to check for the applications concerning you.
If you are dealing with NVIDIA eGPUs, it may be worth trying older versions of Web Drivers, as these may resolve your problems. On the other hand, things are usually uncertain with AMD eGPUs. If your system and monitor settings are optimal, most applications should render using the eGPU, while specific aspects of the applications may require specifically addressing the eGPU on developer-end. Also employ benchmarking tools to confirm your findings.
⇱ eGPU ToolKit & Resources
There are a ton of tools and resources out there to understand and manipulate eGPUs and displays on macOS. There are also fantastic guides on this forum worth a read. This section is your swiss knife to these resources.
For macOS, we need solutions to enable NVIDIA eGPUs as well as eGPUs on non-TB3 macs:
- automate-eGPU-EFI - EFI-based solution that does not modify system files.
- purge-wrangler.sh - Simple script, does not require eGPU to be plugged in, and includes auto-updates, full recovery, etc.
macOS display management has some obvious limitations, especially the ability to disable the internal display. Here are some useful applications to augment display functionality:
- SwitchResX: Advanced display management for macOS with loads of features and the ability to program scripts for display events.
- DisableMonitor: While archived now, this app is still commonly used for it's self-explanatory feature of disabling monitors.
There are several applications for monitoring systems besides Activity Monitor:
- iStat Menus: Leave no stone unturned - all in the menu bar.
- iPulse: An elegant interface to monitor mac performance.
- Macs Fan Control: Great for monitoring system temperatures, with the bonus of controlling system fan speeds.
Additional Guides & Resources
Check out some of these awesome guides & resources:
- Build Guides: See builds by eGPU.io users - they can prove to be invaluable guidance.
- Setup eGPU on Older macOS Versions: If you're one of those that holds out for awhile.
- Resolving eGPU Detection Issues: Sometimes just plugging stuff in doesn't work.
- Updating Thunderbolt Enclosure Firmware: Use the latest firmware for best eGPU results.
- Potentially Accelerate All Apps on eGPU: Possibly a technique to make sure apps use eGPU whenever applicable.
- macOS Boot Performance: Understand macOS boot and improve performance - great for people with multiple installs.
- Apple eGPU Support Document: See what Apple supports with their eGPU implementation.
- Apple Open Source: Examine the innards of some interesting open source components in macOS.
While having a guide is great and all, sometimes users may need a different approach to understanding problems with their eGPU. This is where this section comes in. While most answers may already be in the guide, it can be daunting to find. So let's summarize some common problems and their solutions here: