Optimize external graphics for macs with discrete NVIDIA GPUs.
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
resources Add release badge Nov 26, 2018
.gitignore Update gitignore May 1, 2018
CONTRIBUTING.md Update CONTRIBUTING.md Oct 11, 2017
LICENSE.md
README.md Merge branch 'master' of https://github.com/mayankk2308/purge-nvda Feb 19, 2019
purge-nvda.sh Add refinements + mux intent state Feb 19, 2019

README.md

Header

Script Version macOS Support Github All Releases paypal

PurgeNVDA

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.

Contents

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.

Pre-Requisites

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.

Installation

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

For future use, only the following will be required:

purge-nvda

In case the command above does not work, you can re-use the long installation command and fix the issue.

Some Notes

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

Script Options

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.

Recovery

If you are unable to boot into macOS, boot while pressing ⌘ + S, then enter the following commands:

mount -uw /
purge-nvda -u

This will restore your system to a clean state as documented above.

Post-Install

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.

Known Issues

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 None Use of this patch on applicable macs disables proper sleep 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

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!

Disclaimer

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.

License

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.

Support

If you loved purge-nvda.sh, consider starring the repository or if you would like to, donate via PayPal:

paypal

Thank you for using purge-nvda.sh. This project is currently maintained for any discovered bugs/errors.