purge-nvda.sh is required for certain macs to configure the system further for working external GPU support, alongside purge-wrangler.sh. It may also serve useful for other use cases such as bad discrete GPU chipsets, etc., but is not tested or guaranteed.
A quick run-through of what's included in this document:
- Pre-Requisites
- macOS requirements, pre-system configuration specifics, and more.
- Installation
- Installing and running the script.
- Script Options
- Available capabilities and options in the script.
- Recovery
- Easy way to recover from an unbootable system using the script.
- Post-Install
- System configuration after script installation and some other things of note.
- Known Issues
- A table of known issues and side effects of using the script.
- Troubleshooting
- Additional resources and guides for eGPUs.
- Disclaimer
- Please read the disclaimer before using this script.
- License
- By using this script, you consent to the license that the script comes bundled with.
- Support
- Support the developer if you'd like to.
In case you are not up-to-date, please read Apple's external GPU documentation first to see what is already supported on macOS. The following is a table that summarizes system requirements for using this script:
| Configuration | Requirement | Description |
|---|---|---|
| macOS | 10.13.4+ | Older versions of macOS require different patching mechanisms that this script does not include. Please check eGPU.io for more information. |
| System Integrity Protection | Disabled | By default, this prevents system modifications that the script would like to make, and hence must be disabled. SIP can be disabled as described in this article. |
| Internal GPUs | Intel + NVIDIA | Presence of both an integrated Intel GPU and discrete NVIDIA GPU is required, i.e., iMacs are not supported. Script may be run on iMacs for experimentation. |
purge-nvda.sh auto-manages itself and provides multiple installation and recovery options. Once the pre-requisites are satisfied, install the script by running the following in Terminal:
curl -q -s "https://api.github.com/repos/mayankk2308/purge-nvda/releases/latest" | grep '"browser_download_url":' | sed -E 's/.*"browser_download_url":[ \t]*"([^"]+)".*/\1/' | xargs curl -L -s -0 > purge-nvda.sh && chmod +x purge-nvda.sh && ./purge-nvda.sh && rm purge-nvda.shFor future use, only the following will be required:
purge-nvdaIn case the command above does not work, you can re-use the long installation command and fix the issue.
After using the script, sometimes you may observe that the system is unbootable. In such a case, boot into single user mode as advised in the pre-requisites and set mux to iGPU to force the mux setting. This needs to be done because in some cases, the setting does not apply (after using option 1, 2, 4, or 5 while in macOS).
PurgeNVDA makes it super-easy to perform actions with an interactive menu, and is recommended for most users. Providing no arguments to the script defaults to the menu.
| Argument | Menu | Description |
|---|---|---|
-fa or --fix-amd |
AMD eGPUs | Disables the discrete NVIDIA GPU, sets the gmux to the Intel GPU, allowing any AMD framebuffers to render correctly. Any and all NVIDIA GPUs will be disabled. This patch affects all installations running on the machine and does not modify system files. |
-on or --optimize-nv |
NVIDIA eGPUs | Disables only the internal NVIDIA GPU and sets the gmux to Intel GPU to enable OpenCL/GL acceleration and high performance with NVIDIA eGPUs with a combination of NVRAM + NVDA kernel extension patches. |
-u or --uninstall |
Uninstall | Reverts and removes any system modifications made using the script. If unsuccessful, attempt using it in Single User Mode (Boot with ⌘ + S). |
-sn or --suppress-nv |
Suppress NVIDIA GPUs | Disables all NVIDIA GPUs with fixed cold gmux - therefore affecting all macOS installations running on the machine. This patch does not modify any system files. |
-mi or --mux-igpu |
Set Mux to iGPU | Sets the system graphics multiplexer to the integrated Intel GPU, if available. This preference is after a system boots with its discrete GPU enabled (such that macOS may initialize its framebuffer), thus only lasts for one boot unless appropriate measures to curb dGPU activation are in place. |
-s or --status |
Status | Shows the currently installed patches on the system. Since the mux commands are consumed, mux status will show as inactive/disabled after the chip has been set. |
-d or --donate |
Donate | Launches the default web browser with the set donation link - essentially the same as the PayPal button on this page. |
If you are unable to boot into macOS, boot while pressing ⌘ + S, then enter the following commands:
mount -uw /
purge-nvda -uThis will restore your system to a clean state as documented above.
After installing the script, all settings as described in pre-requisites must persist. For instance, system integrity protection must remain disabled as long as the system is in the patched state.
purge-nvda.sh implements solutions that bring with it multiple undesirable side effects. The following table lists issues and their potential impact on daily usage.
| Issue | Workaround | Description |
|---|---|---|
| Unbootable System | Set Mux to iGPU | Because of the unknown impact of the mux variable in EFI, the patches are sometimes partially applied, thus resulting in an unbootable system. Booting into single user mode and running the workaround re-sets the mux correctly and completes the patch. |
| Sleep & Brightness | None | Use of this patch on applicable macs disables proper sleep and brightness controls completely, including the loss of clamshell sleep modes, that is, the display will not turn off even if the laptop lid is closed. Uninstall recommended for on-the-go use. I cannot investigate further workarounds, but I believe some Hackintosh solutions to enable sleep on iGPU might be applicable. |
| dGPU Power Draw | None | Discrete GPU draws power and emits heat even though it is disabled. I do not have an applicable machine to test further, but this script unfortunately does not include workarounds to address this issue. Perhaps some tweaking with power management and GPU control kexts could make a difference. |
Troubleshooting plays an important role in any kind of hack/patch. New OSes and hardware tend to bring with them new problems and challenges. The hardware chart aims to cover all variances of problems with eGPUs so far, but there can be some specific missed edge cases. The following is a list of additional resources rich in information:
| Resource | Description |
|---|---|
| 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 | Learn about some basics of eGPUs in macOS and find out what means what. This guide does not cover any Windows/Bootcamp-related efforts. |
| eGPU.io Community | The eGPU.io forums are a great place to post concerns and doubts about your setup. Be sure to search the forum before posting as there might be high chance your doubt has already been answered. |
| eGPU Community on Reddit | The reddit community is a wonderful place to request additional help for your new setup, and a good place to find fellow eGPU users. |
My username on both communities is @mac_editor. Feel free to mention my username on eGPU.io posts - I get an email notifying me of the same. In any case, with thousands of members, the community is a welcoming place. Don't be shy!
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 operating system.
The bundled license allows commercial use and redistribution for any purposes. This software comes without any warranty or guaranteed support. By using the script, you agree to adhere to the MIT license. For more information, please see the LICENSE.
If you loved purge-nvda.sh, consider starring the repository or if you would like to, donate via PayPal:
Thank you for using purge-nvda.sh. This project is currently maintained for any discovered bugs/errors.