Document Revision: 6.0.0+
purge-wrangler.sh enables unsupported external GPU configurations on macOS for almost all macs. Before proceeding, please read through this entire document to familiarize yourself with the script, the community, and the resources available you in case you find that you need help.
| Configuration | Specification | When | Description |
|---|---|---|---|
| macOS | 10.13.4+ | Always | Use automate-eGPU.sh for older macOS versions. Also read Apple's external GPU support document. |
| System Integrity Protection | Disabled | Always | When enabled, SIP prevents patching macOS. SIP can be disabled as described in this article. |
| Secure Boot on T2 | No Security | Always | When active, this prevents booting of patched versions of macOS. Settings can be adjusted as shown in this article. |
| External Boot on T2 | Enabled | Optional | An optional but recommended setting. You can change this as described here. |
| Backup | Recommended | Always | A system backup is always recommended before modifying core operating system components. |
Few things of note before you install:
- If you are using an NVIDIA 9xx or newer GPU, only macOS High Sierra is supported. Newer macOS versions do not have available web drivers to accelerate these GPUs. The script will not proceed to patch if appropriate web drivers are not available for your system.
- If you have a Ti82 enclosure such Razer Core V1 and Akitio Thunder3, the script will not be able to determine the GPU installed inside it automatically. In this scenario, the script will ask you what GPU you are using (AMD or NVIDIA).
- If you are using an AMD GPU not listed in Apple's eGPU support document, such as the R9 Nano, legacy support will have to be enabled. In most cases, this will be done automatically. However, as above, if you have a Ti82 enclosure, the script will ask you if you would like to install this.
Download and install using Terminal:
curl -qLs $(curl -qLs https://bit.ly/2WtIESm | grep '"browser_download_url":' | cut -d'"' -f4) > purge-wrangler.sh; bash purge-wrangler.sh; rm purge-wrangler.shFuture use:
purge-wranglerRe-use the full installation command if the shortcut fails to function. purge-wrangler.sh requires administrator privileges to function.
| Menu | CLI Arg | Description |
|---|---|---|
| Setup eGPU | -a |
Automatically set up eGPU based on your system configuration and external GPU. |
| Uninstall | -u |
Uninstalls any system modifications made by the script in-place. This is the recommended uninstallation mechanism. |
| Recovery | -r |
Restores untouched macOS configuration prior to script modifications from a clean component backup. This is a more robust cleanup. |
| System Status | -s |
Shows the current status of some of the components of the system and any modifications made using the script. |
Running without arguments launches the menu.
If you are unable to boot into macOS, boot while pressing ⌘ + S, then enter the following commands:
mount -uw /
purge-wranglerThis will restore your system to a clean state.
With NVIDIA GPUs, hot-unplugging capability is not supported. Additionally, NVIDIA Web Drivers are not required for Kepler-based GPUs as macOS already includes the drivers.
| Integrated GPU | Discrete GPU | External GPU | Dependency | Complications |
|---|---|---|---|---|
| Intel | None | AMD | macOS Drivers | Some models may require plugging in the eGPU after boot. |
| Intel | None | NVIDIA | NVIDIA Web Drivers | Drivers need to be available for the running macOS version. |
| None | NVIDIA | AMD | macOS Drivers | Only internal monitor can be used. Apps can be accelerated using set-eGPU.sh. |
| None | NVIDIA | NVIDIA | NVIDIA Web Drivers | OpenCL/GL compute capabilities may be lost due to NVIDIA Web Drivers. |
| None | AMD | AMD | macOS Drivers | Native or like-native support without any significant complications. |
| None | AMD | NVIDIA | NVIDIA Web Drivers | Conflicting framebuffers may require hot-plugging eGPU and then logging out and in. |
| Intel | NVIDIA | AMD | macOS Drivers | Use purge-nvda.sh if you need external monitors over eGPU. |
| Intel | NVIDIA | NVIDIA | NVIDIA Web Drivers | Use purge-nvda.sh to resolve OpenCL/GL compute loss, and use this boot procedure. |
| Intel | AMD | AMD | macOS Drivers | Native or native-like support without any significant complications. |
| Intel | AMD | NVIDIA | NVIDIA Web Drivers | Slow/black screens which may require switching mux to the iGPU or logging out and in after hot-plugging. |
This section includes a nifty FAQ and additional resources that you can use to get help.
These are some of the most frequently asked questions regarding this script and eGPU support in general. Of course, the list is not exhaustive, so always search for more information via other resources for questions not listed here.
Assuming hardware is appropriately configured and not defective, the only case when the script fails to detect eGPU configurations is when the enclosure has a Ti82 controller, which macOS does not support by default. Hence detection fails. Simply answer the questions the script asks to proceed with your setup.
If asked this question while setting up your eGPU, the answer depends on the NVIDIA GPU you are using. See the installation notes for more insight. Essentially, you don't need these if you are using Kepler GPUs.
In macOS Mojave, Apple removed the necessary APIs that NVIDIA-provided graphics drivers used for accelerating their graphics processors. The script uses a simple check to see if it is possible to run NVIDIA drivers for an older macOS version, and patches it for the new version if so. If not, then patching terminates.
As explained in the installation section, you only need this for AMD GPUs not mentioned in Apple's eGPU Support document. Enabling this for any other GPUs yields no benefit, but is also not harmful.
If you are stuck somewhere, reach out to fellow users:
- eGPU.io Build Guides: See builds for a variety of systems and eGPUs. If you don't find an exact match, look for similar builds.
- eGPU.io Troubleshooting Guide: Some basics on external GPUs in macOS.
- eGPU.io Community: Ask about, request help, learn more, and share your eGPU experience with the community.
- eGPU Community on Reddit: A wonderful place to request additional help for your new setup, and to find fellow eGPU users.
For advanced users and developers willing to test unreleased versions of the script or contributing to the development of the script or its patches, consider reading the PurgeWrangler for Advanced Users & Developers document.
Many thanks to:
- @itsage: For testing the recent releases of the script.
- @fricorico: For help in investigating patches for Thunderbolt 1/2 macs.
- @goalque: For finding patches for NVIDIA eGPUs.
- @fr34k: For investigating macOS components for NVIDIA patches.
And the eGPU.io community for their support and insightful discussion.
This script moves core system files associated with macOS. While any of the potential issues with its application are recoverable, please use this script at your discretion. I will not be liable for any damages to your system.
The bundled license prevents any commercial use, redistribution, and compilation/assembly to obscure code for any purposes. This software comes without any warranty or guaranteed support. By using the script, you agree to adhere to this license. See the LICENSE.
Consider starring the repository or donating via:
Thank you for using purge-wrangler.sh.