Skip to content

Beginner's Guide

Jump to bottom
Mayank Kumar edited this page Jun 14, 2021 · 73 revisions

Kryptonite is now available. This supersedes PurgeWrangler. Please use Kryptonite going forward. PurgeWrangler will only be maintained for bug fixes. Any feature work will be focused on Kryptonite.

This document is the official script guide and guarantees accuracy. There are many articles and video tutorials in many languages across the web and many are not accurate or outdated. This document will guide you through the entire eGPU setup process. If you started by clicking the Clone or download button on the main page, then you've already started wrong. This guide aims to go through the majority of the steps required for setting up the system correctly.

Before moving forward, I suggest opening up this guide on a phone or tablet as the steps will require rebooting your Mac as you go along.

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 system. By using this script, you adhere to its license terms.

Preparations

A system backup is always recommended before using patches on macOS. I suggest using Time Machine. An internet connection is required for downloading some patches. You need to have macOS 10.13.4 or newer.

⚠️ On macOS 11, using this script might prevent delta system software updates. Combo/full replacement updates may be required. FileVault must also be disabled.

⚠️ Legacy Macs running unsupported macOS versions via dosdude patches are not supported. However, Macs that natively supported macOS Catalina could possibly work.

Step 1: Hardware

Ensure that you have the right hardware and it is assembled correctly. Quick checklist:

  • Connect all of the GPU's power connections.
  • Ensure GPU is slotted perfectly into the PCIe slot.
  • Disconnect all Thunderbolt peripherals from your Mac (except displays if required, such as with Mac mini).

⚠️ If you are planning to use an NVIDIA GPU, please note the restrictions. Kepler GPUs may work with limited support.

Step 2A: Disable System Integrity Protection

Before doing anything with the script, we need to prepare your Mac for system modifications and patches. For this, we need to disable System Integrity Protection, commonly known as SIP. However, if you are running macOS 11, you must also disable FileVault before continuing:

  1. Disable FileVault if you are running macOS 11, not required for macOS 10.
  2. Restart your Mac while pressing ⌘R until you see the Apple logo and boot progress bar. This will boot you into macOS Recovery.
  3. For macOS Catalina or newer, you may have to login using your credentials before moving forward.
  4. Once you are in, go to Utilities > Terminal from the menu bar.
  5. Type in the following command in Terminal: 
    csrutil disable
  6. If running macOS 11 or newer, you must also disable ART: 
    csrutil authenticated-root disable

    ⚠️ FileVault needs to be disabled to change ART preferences.

  7. If you have a Mac with the T2 chip, skip to Step 2B. Otherwise reboot the system normally.

SIP and ART are now disabled, and we are ready to install the script. DO NOT RE-ENABLE SIP/ART AFTER USING THE SCRIPT.

Step 2B: Disabling Secure Boot

This step is only applicable if your Mac has the T2 chip. To do this:

  1. Get into Recovery as described previously. If you are following this guide, you are already in Recovery.
  2. Launch Utilities > Startup Security Utility from the menu bar. You might need to provide administrator access.
  3. Choose No Security to completely disable Secure Boot for macOS.
  4. Reboot your system.

Step 3: Installing PurgeWrangler

Now that you are back into macOS, we can proceed to install PurgeWrangler. To do this, launch Terminal. You can search for it in Spotlight, or find it in /Applications/Utilities/. Then copy-paste the following command:

curl -qLs $(curl -qLs https://bit.ly/2WtIESm | grep '"browser_download_url":' | cut -d'"' -f4) > purge-wrangler.sh; sh purge-wrangler.sh; rm purge-wrangler.sh

The latest version of the script will automatically install. After installation succeeds, you should see the PurgeWrangler menu. You will require your administrator account password. If for some reason, installation fails, please try later or install manually.

Step 4: Patching macOS

With PurgeWrangler ready to go, we can begin patching. Before moving forward, ensure that you have your external GPU assembled and ready to connect, and disconnect all other Thunderbolt devices. The script will detect the eGPU configuration and automatically apply patches for you.

  1. Assemble the eGPU.
  2. In the script menu, choose "Setup eGPU" by pressing 1.
  3. Connect your eGPU to your Mac.

⚠️ Things to note:

  • The AMD 5X00 series (Navi) GPUs can crash Thunderbolt 1 & 2 systems when plugging in (#44). This is a macOS bug.
  • If your eGPU enclosure uses the Ti82 chip, GPU details cannot be detected - manual intervention required.

In both cases, system cannot be automatically patched. Please refer to Manual Setup.

The script will now execute. You will see something like this happen:

Once the script completes installing patches, it will attempt to reboot with a countdown. Rebooting is required for the patches to take effect. If you are working on something critical and do not wish to reboot now, press ESC to abort the reboot.

To use the script again, you can simply type the following in Terminal:

purge-wrangler

Manual Setup

You can also set up eGPU support without plugging in your eGPU. In this scenario, you will have to provide additional information.

  1. Ti82 Support: This is for old-generation Thunderbolt 3 devices only. One example is the Razer Core V1. To find out if you need this patch, connect your eGFX enclosure to macOS, go to About This Mac > System Report... > Thunderbolt, and check to see if the device reports as "Unsupported". If so, you need this patch. Otherwise not.
  2. eGPU Vendor: If you are using AMD GPUs, choose AMD. For NVIDIA, choose NVIDIA. Trivial.
  3. Legacy AMD Support: If you are using any GPU not listed in Apple's eGPU support document, you need this.
  4. NVIDIA Web Drivers: Required for any Maxwell (9xx, 750 Ti) or newer NVIDIA GPU.

    ⚠️ macOS Mojave and later do not have web drivers available.

Uninstallation & Recovery

If you do need wish to use the script further, or don't need it anymore, choose the Uninstall option from the menu. This will clear out any system modifications and restore any modified kernel extensions to a clean state.

If for some reason, you are unable to boot into your system, please refer to this page to get up and running again.

Support

If for some reason your setup does not work or you encounter bugs with the script, please refer to the FAQ first. If your issue is not addressed there:

  1. Generate logs from the script using More Options > System Diagnosis & Logging.
  2. Create a new issue.
  3. Fill in the bug report template and upload generated logs.

Manual Installation

In rare cases, the installation command will fail because downloads via Github API, which the command uses, are limited per hour. To bypass this:

  1. Download the script from releases.
  2. Launch Terminal. Type sh followed by a space.
  3. Drag the downloaded script file into Terminal. Your Terminal window will look similar to this:
  4. Press Enter to execute and enter your administrator password.
Clone this wiki locally