# Technical Documentation: dortania/OpenCore-Legacy-Patcher > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/dortania/OpenCore-Legacy-Patcher) ### Overview (README.md)
OpenCore Patcher Logo

OpenCore Legacy Patcher

A Python-based project revolving around [Acidanthera's OpenCorePkg](https://github.com/acidanthera/OpenCorePkg) and [Lilu](https://github.com/acidanthera/Lilu) for both running and unlocking features in macOS on supported and unsupported Macs. Our project's main goal is to breathe new life into Macs no longer supported by Apple, allowing for the installation and usage of macOS Big Sur and newer on machines as old as 2007. ---------- ---------- Noteworthy features of OpenCore Legacy Patcher: * Support for macOS Big Sur, Monterey, Ventura, Sonoma, and Sequoia * Native Over the Air (OTA) System Updates * Supports Penryn and newer Macs * Full support for WPA Wi-Fi and Personal Hotspot on BCM943224 and newer wireless chipsets * System Integrity Protection, FileVault 2, .im4m Secure Boot and Vaulting * Recovery OS, Safe Mode and Single-user Mode booting on non-native OSes * Unlocks features such as Sidecar and AirPlay to Mac even on native Macs * Enables enhanced SATA and NVMe power management on non-Apple storage devices * Zero firmware patching required (ie. APFS ROM patching) * Graphics acceleration for both Metal and non-Metal GPUs ---------- Note: Only clean-installs and upgrades are supported. macOS Big Sur installs already patched with other patchers, such as [Patched Sur](https://github.com/BenSova/Patched-Sur) or [bigmac](https://github.com/StarPlayrX/bigmac), cannot be used due to broken file integrity with APFS snapshots and SIP. * You can, however, reinstall macOS with this patcher and retain your original data Note 2: Currently, OpenCore Legacy Patcher officially supports patching to run macOS Big Sur through Tahoe installs. For older OSes, OpenCore may function; however, support is currently not provided from Dortania. * For macOS Mojave and Catalina support, we recommend the use of [dosdude1's patchers](http://dosdude1.com) ## Getting Started To start using the project, please see our in-depth guide: * [OpenCore Legacy Patcher Guide](https://dortania.github.io/OpenCore-Legacy-Patcher/) ## Support This project is offered on an AS-IS basis, we do not guarantee support for any issues that may arise. However, there is a community server with other passionate users and developers that can aid you: * [OpenCore Patcher Paradise Discord Server](https://discord.gg/rqdPgH8xSN) * Keep in mind that the Discord server is maintained by the community, so we ask everyone to be respectful. * Please review our docs on [how to debug with OpenCore](https://dortania.github.io/OpenCore-Legacy-Patcher/DEBUG.html) to gather important information to help others with troubleshooting. ## Running from source To run the project from source, see here: [Build and run from source](./SOURCE.md) ## Credits * [Acidanthera](https://github.com/Acidanthera) * OpenCorePkg, as well as many of the core kexts and tools * [DhinakG](https://github.com/DhinakG) * Main co-author * [Khronokernel](https://github.com/Khronokernel) * Main co-author * [Ausdauersportler](https://github.com/Ausdauersportler) * iMacs Metal GPUs Upgrade Patch set and documentation * Great amounts of help with debugging, and code suggestions * [vit9696](https://github.com/vit9696) * Endless amount of help troubleshooting, determining fixes and writing patches * [EduCovas](https://github.com/covasedu) * macOS Tahoe patch set * [non-Metal patch set](https://github.com/moraea/non-metal-frameworks) for nVidia Tesla/Fermi/Maxwell/Pascal, AMD TeraScale 1/2, and Intel Core 1st/2nd Generation GPUs * [3802 Metal patch set](https://github.com/moraea/misc-patches/tree/main/3802-Metal-15) and [MetallibSupportPkg](https://github.com/dortania/MetallibSupportPkg) for nVidia Kepler and Intel Core 3rd/4th Generation GPUs * Metal bundle patches and shims for [nVidia Kepler](https://github.com/moraea/misc-patches/tree/main/Kepler%2013%2B), [AMD GCN 1 - 4](https://github.com/moraea/misc-patches/tree/main/GCN%2013%2B), and [AMD GCN 5 (Vega)](https://github.com/moraea/misc-patches/tree/main/vega%2013%2B) * [IOSurface offset patches](https://github.com/moraea/misc-patches/tree/main/Sonoma%2014.4%20IOSurface) for nVidia Kepler, AMD GCN 1 - 5, and Intel Core 3rd - 6th Generation GPUs * [legacy Wi-Fi patch set](https://github.com/moraea/unsupported-wifi-patches) restores functionality for Wi-Fi cards in all 2007 - 2017 models * [T1 patch set](https://github.com/moraea/misc-patches/tree/main/T1-Patch) restores Touch ID, Apple Pay, and other secure functionality in 2016 - 2017 models * AppleGVA downgrade for accelerated video decoding on 2012 - 2016 models * OpenCL and OpenGL downgrade for AMD GCN * [USB 1 patch](https://github.com/moraea/misc-patches/tree/main/IOUSBHostFamily-14.4) * [ASentientHedgehog](https://github.com/moosethegoose2213) * [non-Metal patch set](https://github.com/moraea/non-metal-frameworks) for nVidia Tesla/Fermi/Maxwell/Pascal, AMD TeraScale 1/2, and Intel Core 1st/2nd Generation GPUs * [ASentientBot](https://github.com/ASentientBot) * macOS Tahoe patch set * 3802 MTLCompiler, 31001 MTLCompiler, T1, WiFi patch sets * [dsce](https://github.com/moraea/dsce) and [shared code](https://github.com/moraea/moraea-common) used by some other patches * [cdf](https://github.com/cdf) * Mac Pro on OpenCore Patch set and documentation * [Innie](https://github.com/cdf/Innie) and [NightShiftEnabler](https://github.com/cdf/NightShiftEnabler) * [Syncretic](https://forums.macrumors.com/members/syncretic.1173816/) * [AAAMouSSE](https://forums.macrumors.com/threads/mp3-1-others-sse-4-2-emulation-to-enable-amd-metal-driver.2206682/), [telemetrap](https://forums.macrumors.com/threads/mp3-1-others-sse-4-2-emulation-to-enable-amd-metal-driver.2206682/post-28447707) and [SurPlus](https://github.com/reenigneorcim/SurPlus) * [dosdude1](https://github.com/dosdude1) * Main author of the [original GUI](https://github.com/dortania/OCLP-GUI) * Development of previous patchers, laying out much of what needs to be patched * [parrotgeek1](https://github.com/parrotgeek1) * [VMM Patch Set](https://github.com/dortania/OpenCore-Legacy-Patcher/blob/4a8f61a01da72b38a4b2250386cc4b497a31a839/payloads/Config/config.plist#L1222-L1281) * [BarryKN](https://github.com/BarryKN) * Development of previous patchers, laying out much of what needs to be patched * [mario_bros_tech](https://github.com/mariobrostech) and the rest of the Unsupported Mac Discord * Catalyst that started OpenCore Legacy Patcher * [arter97](https://github.com/arter97/) * [SimpleMSR](https://github.com/arter97/SimpleMSR/) to disable firmware throttling in Nehalem+ MacBooks without batteries * [Mr.Macintosh](https://mrmacintosh.com) * Endless hours helping architect and troubleshoot many portions of the project * [flagers](https://github.com/flagersgit) * Aid with Nvidia Web Driver research and development * [non-Metal patch set](https://github.com/moraea/non-metal-frameworks) for nVidia Tesla/Fermi/Maxwell/Pascal, AMD TeraScale 1/2, and Intel Core 1st/2nd Generation GPUs * [Metal bundle interposer](https://github.com/moraea/misc-patches/tree/main/sequoia%2031001%20interposer) for AMD GCN 1 - 5 and Intel Core 5th/6th Generation GPUs * LegacyRVPL, SnapshotIsKill, etc. to aid in rapid testing and development * [joevt](https://github.com/joevt) * [FixPCIeLinkrate](https://github.com/joevt/joevtApps) * [Jazzzny](https://github.com/Jazzzny) * Research and various contributions to the project * UEFI Legacy XHCI research and development * NVIDIA OpenCL research and development * `MacBook5,2` research and development * LegacyKeyboardInjector * Pre-Ivy Bridge Aquantia Ethernet Patch * Non-Metal Photo Booth Patch for Monterey+ * GUI and Backend Development * Updater UI * macOS Downloader UI * Downloader UI * USB Top Case probing * Developer root patching * Vaulting implementation * macOS 15 3802 Helios Research * UEFI bootx64.efi research * universal2 build research * Various documentation contributions * [crystall1nedev](https://github.com/crystall1nedev) * Various patcher and PatcherSupportPkg contributions * Amazing users who've graciously donate hardware: * [JohnD](https://forums.macrumors.com/members/johnd.53633/) - 2013 Mac Pro * [SpiGAndromeda](https://github.com/SpiGAndromeda) - AMD Vega 64 * [turbomacs](https://github.com/turbomacs) - 2014 5k iMac * [vinaypundith](https://forums.macrumors.com/members/vinaypundith.1212357/) - MacBook7,1 * [ThatStella7922](https://github.com/ThatStella7922) - 2017 13" MacBook Pro (A1708) * zephar - 2008 Mac Pro * jazo97 - 2011 15" MacBook Pro * And others (reach out if we forgot you!) * MacRumors and Unsupported Mac Communities * Endless testing and reporting issues * Apple * for macOS and many of the kexts, frameworks and other binaries we reimplemented into newer OSes --- ### README (`docs/README.md`) --- home: true heroImage: /homepage.png heroText: OpenCore Legacy Patcher actionText: Getting Started→ actionLink: START.md meta: - name: description content: Experience macOS just like before features: # - title: Built with security in mind # details: Supporting System Integrity Protection(SIP), FileVault 2, .im4m Secure Boot and Vaulting. We make an effort to ensure your system is as secure as possible. - title: Near-native OTA updates details: Install updates from System Settings, with just couple more additional steps compared to native. - title: Zero firmware patching details: Using the capabilities of the OpenCore boot manager, our protocol upgrades are done in memory and are never permanent. - title: Supporting more hardware details: New life is breathed into your decade-old graphics card, WiFi, and Bluetooth chipsets. Even your upgraded hardware receives benefits by unlocking exciting features like Hardware Acceleration, AirDrop, Apple Watch Unlock, Sidecar, and much more! - title: Unlock newer features details: Unlock some newer features such as Sidecar, AirPlay to Mac, Night Shift, and Universal Control, even on natively supported models! - title: A helpful community details: Whether it's getting started or learning the specifics, you can always find answers with our amazing community of tinkerers, developers, and dreamers. footer: Copyright © Dortania 2020-2025 --- --- ### ACCEL (`docs/ACCEL.md`) This page has moved. * [Application troubleshooting](./TROUBLESHOOT-APP.md) * [Booting, installer and other troubleshooting](./TROUBLESHOOT-MISC.md) * [Non-Metal troubleshooting](./TROUBLESHOOT-NONMETAL.md) * [Hardware troubleshooting](./TROUBLESHOOT-HARDWARE.md) --- ### BOOT (`docs/BOOT.md`) # Booting OpenCore and macOS Now we finally get to boot OpenCore! Reboot the machine while holding `Option` to select the EFI Boot entry with the OpenCore icon (holding the `Control` key will make this the default boot entry): * This will be the Mac Boot Picker
EFI boot
::: details Note for Mac Pros/Xserves/iMacs with unflashed GPUs (Adapted from the [OpenCore on the Mac Pro guide](https://forums.macrumors.com/threads/opencore-on-the-mac-pro.2207814/)) For Mac Pro, Xserve and, iMac users with non-flashed GPUs, you can still easily boot OpenCore and view the entire boot process. Firstly, open the Terminal and run the following command: ```sh sudo nvram "recovery-boot-mode=unused" && sudo reboot recovery ``` This will make your machine reboot into the Recovery Environment. Alternatively, holding `Command` + `R` when your machine is starting up will also let you enter the Recovery. Secondly, open the Recovery Environment's Terminal (Menu bar > Utilities > Terminal). Now you'll want to get a list of drive identifiers. To do so, run the following command: ```sh diskutil list ``` The command should produce a list of drives installed in your system:
Unflashed boot
Keep track of the drive with the OCLP install. You will need the drive identifer for later. Now you'll want to mount the EFI partition (where OCLP is installed, though it may differ if you've installed OCLP to a FAT-32 volume). Run the following command (Replace X with the drive number): ```sh diskutil mount diskXs1 ```
Unflashed boot 2
If everything is correct, the EFI partion should be mounted. Now you'll want to use the `bless` command to set the default boot device: ```sh bless --mount /Volumes/EFI --setBoot --file /Volumes/EFI/System/Library/CoreServices/boot.efi ``` Once the command is run, it should produce no output.
Unflashed boot 3
If the command produces an output, ensure that you've typed it in correctly. Now you can reboot your machine. OCLP is now the default boot option! ::: Now that you've loaded OpenCore, "select Install macOS": * This will be the OpenCore Picker
OpenCore boot
You will soon reach the installer screen! If you enabled verbose mode when building OCLP, a lot of text will run across the screen. From there, it's just like any normal macOS install. For an example of how the boot process looks, see the following video: * [OpenCore Legacy Patcher Boot Process](https://www.youtube.com/watch?v=AN3zsbQV_n4) **Important:** If you're using a brand new disk that has not been used before, choose "View -> Show all devices" in Disk Utility and format the entire disk by choosing the topmost option in the sidebar to avoid a missing internal EFI later when trying to boot OpenCore to internal disk.
Wipe disk
::: warning Warning for T1 Macs When installing macOS Sonoma or newer on a T1 system (2016-2017), full disk wipe will remove T1 functionality (touchbar etc). Therefore when installing, only wipe the volume containing the operating system.
WipeVolume
[More info here](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOT-HARDWARE.html#no-t1-functionality-after-installing-sonoma-or-newer) ::: If your Mac is looping back into the beginning of the setup after the first reboot, turn it off, start it again and hold Option. This time (after choosing `EFI Boot` first) select the option with a grey hard disk icon in the OpenCore picker. It can either say `macOS Installer` or the name you gave the disk during the installer process. Keep repeating this step after every reboot if necessary.
Stuck on first reboot
::: warning **MacBookPro11,3 Note**: When booting macOS Monterey, you'll need to boot into safe mode if acceleration patches are not installed yet. [Otherwise, you'll hit a black screen due to missing NVIDIA drivers.](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/522) Safe Mode can be entered by holding `Shift + Enter` when selecting macOS Monterey in OCLP's Boot Menu. ::: # Once installed and booting, head to [Post-Installation](./POST-INSTALL.md) --- ### BUILD (`docs/BUILD.md`) # Building and installing OpenCore Now that we have a macOS installer, let's now build our OpenCore configuration! If you haven't downloaded OpenCore Patcher yet, do so now: * [OpenCore Legacy Patcher Releases](https://github.com/dortania/Opencore-Legacy-Patcher/releases) Next, run the `OpenCore-Patcher.app` Here we'll select Build and Install OpenCore and start building:
OCLP GUI Main Menu
::: warning OpenCore configurations are hardware specific. If you're building OpenCore for a different model than you're currently running, it is absolutely necessary to select the proper model from Settings. ::: | Start Building | Finished Building | | :--- | :--- | | Build start | Build finished | Once it finishes building, you'll want to select the Install OpenCore button: * If you created a macOS USB manually and don't see it listed, make sure it's either formatted as GUID/GPT or has a FAT32 partition for OpenCore to reside on. | Select Drive | Select Partition | | :--- | :--- | | Select disk | Select partition | # Once finished, head to [Booting OpenCore and macOS](./BOOT.md) --- ### DEBUG (`docs/DEBUG.md`) # How to debug with OpenCore For those who've hit an odd bug and are unsure if it's user error or within the patcher, we recommend asking on the [OpenCore Patcher Paradise Discord Server](https://discord.gg/rqdPgH8xSN) for help. ## Debugging yourself The easiest way to debug yourself is via Patcher Settings. Here there are many different settings, however, the 3 main options that will help are: * "Enable Verbose Mode" * "Enable OpenCore DEBUG" * "Enable Kext DEBUG"
OCLP debug
When you've enabled these 3 options, rebuild OpenCore and install to your drive. This will provide much greater debug information as well as write logs to the EFI Partition. ## Obtaining OpenCore logs from disk With "Enable OpenCore DEBUG" set, on every boot there will be a .txt file generated on the EFI Partition. To grab these logs, [download and run MountEFI](https://github.com/corpnewt/MountEFI):
Mount EFI
Once you've mounted the EFI Partition of the drive you have macOS on, you should see some nice logs:
Mount EFI
## Obtaining Kernel logs from macOS With "Enable Kext DEBUG" set, every boot will now have much more detailed logs stored in the OS. To get these logs, simply run the below command: ```sh sudo dmesg > ~/Desktop/DMESG.txt ``` From there, you'll have a log on your desktop. ## Filing an issue with us ::: warning Currently issues have been disabled due to [current events](ISSUES-HOLD.md). You can continue to receive support in the [OpenCore Patcher Paradise Discord Server](https://discord.gg/rqdPgH8xSN), where there are active members of the community available. ::: Now that you have proper logs, you can now [file issues with us](https://github.com/dortania/OpenCore-Legacy-Patcher/issues). This is a reminder to include the following info: * Model that you're patching for (ie. MacBookPro10,1) * Target OS (ie. macOS 11.2.3) * Host OS (ie. macOS 10.15.7) * Upload of your OpenCore Build Folder * Upload of your OpenCore log (if applicable) * Upload of your Kernel log (if applicable) Additionally, please search to see if the issue has been reported before. This avoids having duplicate issues. --- ### DONATE (`docs/DONATE.md`) # Supporting the patcher We have opened OpenCollective in order to manage donations as well as be transparent about where the donated money is going. If you want to support the patcher with money donation, you can do so below. [OpenCollective](https://opencollective.com/opencore-legacy-patcher) If you wish, you can also donate legacy hardware you don't need anymore as long as it makes sense logistically. In this case, reach out on the Discord server. --- ### FAQ (`docs/FAQ.md`) # FAQ * [Application requirements](#application-requirements) * [Application versioning](#application-versioning) * [How do I make sure I'm all up to date?](#how-do-i-make-sure-i-m-all-up-to-date) * [Where are the GUI settings saved?](#where-are-the-gui-settings-saved) * [Can I use the same USB install media as a universal installer?](#can-i-use-the-same-usb-install-media-as-a-universal-installer) * [Can I use OTA updates?](#can-i-use-ota-updates) * [Can I use automatic updates?](#can-i-use-automatic-updates) * [Why are macOS updates so large?](#why-are-macos-updates-so-large) * [Can I update to macOS betas?](#can-i-update-to-macos-betas) * [Can I downgrade macOS while keeping data?](#can-i-downgrade-macos-while-keeping-data) * [Why is my system slow?](#why-is-my-system-slow) * [Applications crashing with "illegal instruction"](#applications-crashing-with-illegal-instruction) * [What is Metal and non-Metal?](#what-is-metal-and-non-metal) * [What are FeatureUnlock and mediaanalysisd?](#what-are-featureunlock-and-mediaanalysisd) * [Why isn't iPhone Mirroring working?](#why-isn-t-iphone-mirroring-working) * [Where is Apple Intelligence?](#where-is-apple-intelligence) ## Application requirements The patcher application requires **OS X Yosemite 10.10** or later to run. Due to limitations with Apple's `createinstallmedia` tool used for installer creation, the following are required: * **El Capitan 10.11** to make installers for macOS Ventura. * **High Sierra 10.13** to make installers for macOS Sonoma and newer. The patcher is designed to target **macOS Big Sur 11.x to macOS Sequoia 15.x**. * Other versions may work, albeit in a broken state. No support is provided for any version outside of the above. ## Application versioning Since 1.0.0, OCLP adheres to a proper versioning scheme with major, minor and bug fix system ([Semantic Versioning](https://semver.org/)). - First digit: Major changes, including new OS support, API changes, and significant patch set changes, etc - Second digit: Minor changes, including incoming OS update fixes, minor patch set changes, etc - Third digit: Bug fixes, primarily hot fixes either due to a regression in prior release or resolving issues in already released OS updates ## How do I make sure I'm all up to date? Updating the OCLP installation is a three step process, first the application, second the bootloader and finally root patches. Refer to [Updating OpenCore and patches](https://dortania.github.io/OpenCore-Legacy-Patcher/UPDATE.html) for how to update the application and patches. ## Where are the GUI settings saved? In OpenCore Legacy Patcher 2.1.0 and newer, the status of settings are saved under ```/Users/Shared/.com.dortania.opencore-legacy-patcher.plist```. The application will utilize this file to keep track of and retain settings for relaunches and application updates, no longer requiring a reconfiguring each time. The user interface will reset if any model other than "Host Model" is selected, as building for a different model will require different settings. In case of issues, delete the file and restart the application to revert the GUI to default settings, then rebuild OpenCore with newly configured settings. **Ticking the options in Settings alone will not apply the settings until the "Build and Install OpenCore" process has been redone**, which rebuilds a new OpenCore with the selected settings. Applied settings are saved to a config.plist file inside your EFI partition by the building process. ::: warning Only settings made within OCLP are accounted for, modifications made directly into the ```config.plist``` file in the EFI partition outside of OCLP **will continue to reset**. Additionally, modifying ```config.plist``` manually may lead to a state where settings showed in the GUI are not in sync compared to settings in use, due to the application not knowing whether the file has been manually modified. ::: In versions older than 2.1.0, the status of settings was not tracked. Therefore in these versions GUI will continue to reset to defaults after every launch, requiring settings to be reconfigured each time. ## Can I use the same USB install media as a universal installer? OpenCore configurations are device specific, due to different quirks needed for different systems. If you are building OpenCore for a different system that you're running, you will have to select the targeted model from Settings before building OpenCore on the USB media. When building OpenCore on a different system, OCLP cannot be aware of all the hardware installed in the target, meaning safe defaults will be used. However, this may not be the most optimal experience especially with custom hardware. As such it's recommended to rebuild OpenCore **on device** to apply settings that are based on hardware detection, after the OS has been installed. ## Can I use OTA updates? You can. However it is extremely recommended to use USB drive for major OS upgrades (such as 13 -> 14) to avoid larger issues from potentially occurring. General updates are usually fine, though it is always a good idea to wait few days to see whether patches break and have to be fixed. See more information about updating in [Preparing OCLP for macOS update.](https://dortania.github.io/OpenCore-Legacy-Patcher/UPDATE.html#preparing-oclp-for-macos-update) ## Can I use automatic updates? It is extremely recommended to disable automatic updates (even downloading) when using OCLP, as Apple has recently changed the way automatic updates work. Updates are now getting staged during the download process and are already modifying the system volume, which can lead to broken system out of nowhere since the operating system gets into a liminal state between two versions. You can still manually initiate an update when you're ready to do so. For a related "System version mismatch" error while root patching and more information, refer to [System version mismatch error when root patching](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOT-APP.html#system-version-mismatch-error-when-root-patching) for troubleshooting. * Note: macOS Sequoia has begun prompting to enable automatic updates from 15.4 onward after an update install has finished and isn't giving a choice to fully decline, this means you may have to keep doing it again after updating to newer versions. ::: details How to disable updates (click to expand) **macOS Ventura and newer:** System Settings -> General -> Software Update -> (i) button next to Automatic Updates -> Disable "Download new updates when available". **macOS Big Sur and Monterey:** System Preferences -> Software Update -> Advanced -> Disable "Download new updates when available". ::: ## Why are macOS updates so large? macOS by default uses a sealed system volume that is unwritable. When the seal is broken, macOS thinks the volume is broken and downloads a full copy of macOS for every update to "repair" it to a known state. In order for root patching to work, this seal has to be broken since root patching by design requires on-disk file manipulation. This is also why root patches have to be reinstalled after each update. ## Can I update to macOS betas? OCLP patch development and testing happens at the beta phase in order to target a stable release, as such it is impossible for OCLP to support betas properly and previous versions may be incompatible. Only install a beta if you know what you're doing, have your expectations in check and don't mind having to fully reset to recover your system. Be advised that no help will be given in situations where a beta was installed. ## Can I downgrade macOS while keeping data? macOS doesn't allow direct downgrades, as such you will have to wipe the disk in order to revert. Backup your data beforehand either via Time Machine, ASR or some other solution. ## Why is my system slow? #### Lacking or broken root patches If your system is being **really** slow and macOS is lacking wallpaper and transparency in Dock and menubar, make sure to install root patches to get proper drivers and functionality. Refer to [Applying post install volume patches](https://dortania.github.io/OpenCore-Legacy-Patcher/POST-INSTALL.html#applying-post-install-volume-patches) section for more information. **Root patches will be wiped by macOS updates and have to be reinstalled after an update finishes.** Patches can also break if automatic updates are enabled and an update prematurely modifies the system volume, refer to [System version mismatch error when root patching](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOT-APP.html#system-version-mismatch-error-when-root-patching) for more information. #### Spotlight If your macOS installation is recent, Spotlight starts creating a full disk index which can cause high CPU load, high temps and general slowness. It's recommended to keep the system running for few hours, once Spotlight has indexed the load will ease. A way to check whether it's caused by Spotlight is to open Activity Monitor, choosing "All Processes" from the "View" menu item, then sorting by the CPU value to see if a process called ```mds_stores``` is using a lot of CPU resources. #### Heavier macOS versions Newer operating systems are harder to run and can appear more slow. If this is the case, there is not a whole lot to do about it. #### Thermal issues or bad/missing battery If you see ```kernel_task``` hogging a lot of CPU resources in Activity Monitor (this also requires View -> All Processes), this means the system is being throttled mostly due to the following reasons: In laptops, if the battery is either missing or in bad condition, macOS will throttle the CPU quite hard in order to stay running as the charger cannot provide enough power for peak performance. You may try disabling throttling in OCLP settings but this usually leads to unexpected shutdowns during load, when the charger runs out of power to provide. Additionally, trackpad settings will be unavailable on laptops if battery is not present. Thermal issues can also throttle the CPU, in this case it may be recommended to repaste the system. You can use [Intel Power Gadget (Web Archive)](https://web.archive.org/web/20220701164200/https://www.intel.com/content/dam/develop/external/us/en/documents/downloads/intel-power-gadget.dmg) to monitor CPU frequency, AVG and REQ should mostly match each other. ## Applications crashing with "illegal instruction" If the crash log includes a string saying "illegal instruction", this typically means the application requires AVX or AVX2 CPU instructions. Since macOS Ventura, AVX2 is required from all Macs supported by it. While OCLP is able to patch macOS to boot without it, many applications are beginning to utilize AVX and AVX2 as well in newer versions because all supported Macs are expected to have them. This creates an issue for older systems where some applications cannot be ran on CPUs lacking such instructions. Some older Macs may need older versions of applications and cannot update to newer versions. AVX was introduced in Sandy Bridge CPU generation and AVX2 in Haswell generation. In essence, this means that some models are now aging rapidly and newer OS won't always provide support for newer applications because of hardware requirements. If an application still supports macOS versions older than Ventura, it may have a chance of running on an older OS version on the old system, since some Macs running them natively don't support AVX2 and the app takes a different path. ::: details Earliest Mac models supporting AVX instruction (click to expand) - Macmini5,x (2011) - iMac12,x (2011) - MacBookPro8,x (2011) - MacBookAir4,x (2011) - MacBook8,x (2015) - MacPro6,1 (2013) ::: ::: details Earliest Mac models supporting AVX2 instruction (click to expand) - Macmini7,x (2014) - iMac14,x (2013) - MacBookPro11,x (2013) - MacBookAir6,x (2013) - MacBook8,x (2015) - MacPro7,1 (2019) ::: ## What is Metal and Non-Metal? Metal is Apple's proprietary graphics API that acts as a replacement for OpenGL/OpenCL which fully superseded OpenGL rendering of the operating system starting from macOS Mojave. When the word "Non-Metal" is used, it describes GPUs that are not Metal supported and require using OpenGL instead. Due to deprecation of OpenGL, many newer applications may require Metal rendering and as such will fail to run on systems with Non-Metal GPUs. Some built-in apps like Maps and everything relying on it (such as Find My) will fail to render as well on versions later than Big Sur. A great rule of thumb is that Macs older than 2012 are non-Metal, with the exception of systems having upgradable GPUs. ::: details macOS GPU Chart Intel GMA series is completely unsupported, even when using OpenCore Legacy Patcher. AMD Navi (RX 5000 - 6000 series) GPUs are non-functional in Mac Pro 2008 to 2012 using Ventura and newer due to lack of AVX2 support. | Graphics Vendor | Architecture | Series | Supports Metal | | :--- | :--- | :--- | :--- | | ATI | TeraScale 1 | HD 2XXX - HD 4XXX | No | | ^^ | TeraScale 2 | HD 5XXX - HD 6XXX | ^^ | | AMD | GCN (and newer) | HD 7XXX+ | Yes | | NVIDIA | Tesla | 8XXX - 3XX | No | | ^^ | Fermi | 4XX - 5XX | ^^ | | ^^ | Kepler | 6XX - 7XX | Yes | | ^^ | Maxwell | 8XX - 9XX | No (on 10.14 and newer) | | ^^ | Pascal | 10XX | ^^ | | Intel | GMA | GMA 900 - GMA X3000 | No | | ^^ | Iron Lake | HD series | ^^ | | ^^ | Sandy Bridge | HD 3000 | ^^ | | ^^ | Ivy Bridge (and newer) | HD 4000 | Yes | ::: Refer to the following pages for more information - [Supported models](https://dortania.github.io/OpenCore-Legacy-Patcher/MODELS.html) - [Non-Metal GitHub issue](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108) - [Non-Metal Issues](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOT-NONMETAL.html) - [Hardware troubleshooting](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOT-HARDWARE) ## What are FeatureUnlock and mediaanalysisd? **Important:** These features have the potential to cause instability in many places and as such a decision has been made to disable them by default (mediaanalysisd only on 3802-based* systems) starting from OpenCore Legacy Patcher version 2.1.0. If you want to enable these features at the risk of additional instability, you can do so in the OCLP settings and rebuilding OpenCore. FeatureUnlock may also have issues functioning with some OS versions and systems due to race condition during system bootup. If this happens to you, try rebooting multiple times or different (older) OS versions to see if it will remedy the issue. FeatureUnlock is an extension to enable some macOS features, including: - Sidecar - Universal Control - AirPlay to Mac - Continuity Camera - NightShift (non-Metal) Further information, requirements and the models affected for FeatureUnlock features can be found [here](https://github.com/acidanthera/FeatureUnlock). Medianalysisd is utilized for - Face detection in Photos - Live Text | FeatureUnlock | mediaanalysisd | | :--- | :--- | | | | ::: details *3802 systems list (click to expand) * NVIDIA * Kepler (600-800 series GPUs) * Intel * Ivy Bridge (3rd generation, HD 4000 series GPUs) * Haswell (4th generation, HD/Iris 4000-5000 series GPUs) These GPUs are typically met in systems from 2012-2015. ::: ## Why isn't iPhone Mirroring working? iPhone Mirroring requires a T2 chip, which means it will not be available on OCLP patched systems. The connection fails due to failure to establish T2 attestation. ## Where is Apple Intelligence? Apple Intelligence requires Neural Engine, which is only found in Apple Silicon chips. --- ### HOW (`docs/HOW.md`) # Boot Process with OpenCore Legacy Patcher OpenCore Legacy Patcher itself is actually quite a "dumb" program. It essentially edits a config.plist file and moves files around, actually having little logic regarding the boot process. The real magic of OCLP is [OpenCorePkg](https://github.com/acidanthera/OpenCorePkg), our back-end, and what makes this patcher so powerful. ## Boot Process with OpenCore To understand a bit more of how OpenCore is able to revive older Macs in such a native-like way, we need to go over *how* OpenCore works with your Mac: --- ### ICNS (`docs/ICNS.md`) # Creating custom icons for OpenCore and Mac Boot Picker For users who want to customize their setup to be more personal, OpenCore does allow for custom icons and images in the boot picker. * [Custom OpenCore icons](#custom-opencore-icons) * [Custom Mac Boot Picker icons](#custom-mac-boot-picker-icons) * [Installing updated icons](#installing-updated-icons) # Custom OpenCore icons To generate custom OpenCore icons, you'll need the following: * Images in PNG format * Each image, with the following res: * Cursor — Mouse cursor (mandatory, up to 144x144). * Selected — Selected item (mandatory, 144x144). * Selector — Selecting item (mandatory, up to 144x40). * Left — Scrolling left (mandatory, 40x40). * Right — Scrolling right (mandatory, 40x40). * HardDrive — Generic OS (mandatory, 128x128). * Background — Centred background image. (Recommended max size 1920x1080) * Apple — Apple OS (128x128). * AppleRecv — Apple Recovery OS (128x128). * AppleTM — Apple Time Machine (128x128). * Windows — Windows (128x128). * Other — Custom entry (see [Entries](https://dortania.github.io/docs/latest/Configuration.html), 128x128). * ResetNVRAM — Reset NVRAM system action or tool (128x128). * Shell — Entry with UEFI Shell name for e.g. OpenShell (128x128). * Tool — Any other tool (128x128). Note, for each image we recommend having one of double the size. This ensures that icons are scaled correctly since .icns support dedicated images depending on HiDPI or not. Once you have a custom image you want to use(for example, as a background), download the [latest release of OpenCorePkg](https://github.com/acidanthera/OpenCorePkg/releases) and enter the `Utilities/icnspack/` folder: Now `cd` to this folder in terminal and run the following: ```sh ./icnspack Background.icns ``` Once done, you'll see your custom icon generated in `icnspack`'s folder: # Custom Mac Boot Picker icons Custom boot picker icons are much more complicated on Legacy Macs. On late 2013+ Macs, the [Custom OpenCore icons](#custom-opencore-icons) method will work just fine. However, on many 2012 and older Macs, the icons generated will be incompatible with the firmware. To generate legacy icons, you'll need the following: * A machine running macOS 10.4 through 10.11 * Icon Composer.app (Requires Apple Developer Account for official download) * Users without a developer account can find mirrors here: * [Icon Composer 10.6](https://github.com/dortania/OpenCore-Legacy-Patcher/blob/main/docs/Icon-Composer-10.6.zip) * [Icon Composer 10.11](https://github.com/dortania/OpenCore-Legacy-Patcher/blob/main/docs/Icon-Composer-10.11.zip) * PNG Image you wish to convert Head to [developer.apple's More Downloads page](https://developer.apple.com/download/more/) and search for `Graphics Tools` that is supported by your OS(note for 10.6 and older, the app is hidden inside `Developer Tools`): Once downloaded, open the disk image and you'll find Icon Composer.app: Now run the app and simply drag the images to each section as so: Now save and export the new icns file. # Installing updated icons To install, please ensure that Vault was disabled when you built OpenCore. If you're unsure, simply rebuild OpenCore with the Patcher setting "Vault" set to false. * Warning: Editing your OpenCore EFI incorrectly can result in a bricked install. Please ensure you have a natively supported version of macOS installed to boot into in case of issues. Now that you've verified that you can edit OpenCore safely, you'll need to mount the drive that OpenCore is stored on. To do this, download [MountEFI](https://github.com/corpnewt/MountEFI) and run it: Select the drive you installed OpenCore to and mount it. * [Updating OpenCore icons](#updating-opencore-icons) * [Updating Mac Boot Picker icons](#updating-mac-boot-picker-icons) ### Updating OpenCore icons Head to `EFI/OC/Resources/Image/` on your drive and you'll see all the custom icons. For Background.icns, we need to ensure the file matches the theme OpenCore has set so we add the prefix `Modern` to it: Now reboot and you should see your updated icon(s)! ### Updating Mac Boot Picker icons Updating the Mac Boot Picker icons is actually quite simple. On the root of your drive, simply drop the icon into the root of the drive with the name `.VolumeIcon.icns` Now reboot and you'll see the new icon! --- ### INSTALLER (`docs/INSTALLER.md`) # Creating macOS Installers This document is centered around downloading and writing the macOS installer to a USB drive. If you're planning to install macOS on other system than you're currently running, it is recommended to choose the Mac model in Settings now before proceeding, so that automatic root patching works correctly later on. * Note: A 32GB drive is recommended, later versions of Sonoma and Sequoia cannot fit installer and patches to a 16GB disk. 16GB drive may work for older versions. Before proceeding, please read the application and macOS installer creation requirements [from the FAQ.](https://dortania.github.io/OpenCore-Legacy-Patcher/FAQ.html#application-requirements) Newer macOS versions require you to be on a newer base OS before you can create an installer, due to requirements of Apple's `createinstallmedia` tool OCLP uses as its backbone. ## Downloading the installer To start off, you'll want to grab the app: * [OpenCore Legacy Patcher Release Apps](https://github.com/dortania/OpenCore-Legacy-Patcher/releases) Once downloaded, open the app and you should be greeted by the main menu. First, we'll want to select the "Create macOS Installer" button. This will present you with 2 options. For this example, we'll assume you'll need an installer. Select the "Download macOS installer" to get you a list of installers. Click to download the version you want. | Main menu | Installer creation menu | Available installers | | :--- | :--- | --- | | | | | ## Creating the installer Once the download is finished, you can proceed to write the installer onto a USB drive. * Note: The entire USB drive will be formatted | Select Downloaded Installer | Select disk to format | | :--- | :--- | | Select local installer | Select disk to format | Now the patcher will start the installer flashing! | Flashing | Success Prompt | Finished Flashing | | :--- | :--- | :--- | | | | | # Once finished, head to [Building and installing OpenCore](./BUILD.md) --- ### ISSUES HOLD (`docs/ISSUES-HOLD.md`) # The current hold on new issues and pull requests As written with the release of OpenCore Legacy Patcher 0.4.3, and macOS 12.3: > With today's macOS 12.3 release, I decided it would be best to release this build of OpenCore Legacy Patcher to ensure some important issues are resolved with today's release (namely Open/Save dialog problem introduced by Apple in the 12.3 Betas) > > As the situation develops back home with my family in Ukraine, I am unlikely to continue the development of OpenCore Legacy Patcher in the near future. At most, there may be potential PatcherSupportPkg updates from ASentientBot and the rest of the amazing non-Metal development team however otherwise development may potentially be taken over by others later on. Issues will continue to remain closed for the time being. > > With regards to the future of this project, this release should be treated as its last major release for the next couple of months. When WWDC2022 is presented, I hope my country will be in a calmer situation where we can tinker with Macs again peacefully. > > This is not a final goodbye for me with this project, just a round-about way to say I'll be returning someday. I want to give the biggest thank you's to the community and to the many amazing developers within it. OpenCore Legacy Patcher is not just my project, it's the cumulation of many people that are all responsible for where we are today. > > -- Mykola If you encounter new issues with the patcher that do not have solutions easily available, our helpful community in the [OpenCore Patcher Paradise Discord Server](https://discord.gg/rqdPgH8xSN) can provide support in the meantime. You should still provide as much information as you can by [gathering debug logs](DEBUG.md) when you ask for help. --- ### MODELS (`docs/MODELS.md`) # Supported Models Any Intel-based Mac listed below can install and make use of OpenCore Legacy Patcher. To check your hardware model, open System Information and look for the `Model Identifier` key. * This applies even if Apple supports the model natively. * OpenCore Legacy Patcher does not support PowerPC- or Apple Silicon-based Macs. * If your model is not listed below, it is not supported by this patcher. ::: warning Note It is **extremely recommended** to update your Mac to its latest native version before using OpenCore Legacy Patcher, to ensure you're on the highest firmware. ::: ::: warning 3GB+ RAM required for installing macOS Sonoma and newer Models with 2GB RAM will not be able to install macOS Sonoma or macOS Sequoia, additionally macOS Sequoia may be unable to boot. These versions may be installed using a disk swap method where installation is done on another system but your mileage may vary and this is not recommended. ::: The below tables can be used to reference issues with a particular model, and see which OS would work best on your machine. * [MacBook](#macbook) * [MacBook Air](#macbook-air) * [MacBook Pro](#macbook-pro) * [Mac mini](#mac-mini) * [iMac](#imac) * [Mac Pro](#mac-pro) * [Xserve](#xserve) ### MacBook | Model Name | Identifier | Additional info | | :--- | :--- | :--- | | MacBook (13-inch, Aluminum, Late 2008) | `MacBook5,1` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021)| | MacBook (13-inch, Early 2009)
MacBook (13-inch, Mid 2009) | `MacBook5,2` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021)
- Trackpad gestures are partially broken | | MacBook (13-inch, Late 2009) | `MacBook6,1` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021) | | MacBook (13-inch, Mid 2010) | `MacBook7,1` | ^^ | | MacBook (Retina, 12-inch, Early 2015) | `MacBook8,1` | - [Legacy Metal (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008) | | MacBook (Retina, 12-inch, Early 2016) | `MacBook9,1` | ^^ | | MacBook (Retina, 12-inch, 2017) | `MacBook10,1` | - Native graphics support | ### MacBook Air | Model Name | Identifier | Additional info | | :--- | :--- | :--- | | MacBook Air (13-inch, Late 2008)
MacBook Air (13-inch, Mid 2009) | `MacBookAir2,1` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021)| | MacBook Air (11-inch, Late 2010) | `MacBookAir3,1` | ^^ | | MacBook Air (13-inch, Late 2010) | `MacBookAir3,2` | ^^ | | MacBook Air (11-inch, Mid 2011) | `MacBookAir4,1` | ^^ | | MacBook Air (13-inch, Mid 2011) | `MacBookAir4,2` | ^^ | | MacBook Air (11-inch, Mid 2012) | `MacBookAir5,1` | - [Legacy Metal (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008) | | MacBook Air (13-inch, Mid 2012) | `MacBookAir5,2` | ^^ | | MacBook Air (11-inch, Mid 2013)
MacBook Air (11-inch, Early 2014) | `MacBookAir6,1` | ^^ | | MacBook Air (13-inch, Mid 2013)
MacBook Air (13-inch, Early 2014) | `MacBookAir6,2` | ^^ | | MacBook Air (11-inch, Early 2015) | `MacBookAir7,1` | ^^ | | MacBook Air (13-inch, Early 2015)
MacBook Air (13-inch, 2017) | `MacBookAir7,2` | ^^ | | MacBook Air (Retina, 13-inch, 2018) | `MacBookAir8,1` | - Supported natively up to Sonoma
- [Currently not supported with OpenCore due to T2 issues](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1136)
| | MacBook Air (Retina, 13-inch, 2019) | `MacBookAir8,2` | ^^ | | MacBook Air (Retina, 13-inch, 2020) | `MacBookAir9,1` | Supported by Apple | ### MacBook Pro | Model Name | Identifier | Additional info | | :--- | :--- | :--- | | MacBook Pro (15-inch, Early 2008)
MacBook Pro (17-inch, Early 2008) | `MacBookPro4,1` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021)| | MacBook Pro (15-inch, Late 2008)
MacBook Pro (15-inch, Early 2009) | `MacBookPro5,1` | ^^ | | MacBook Pro (17-inch, Early 2009)
MacBook Pro (17-inch, Mid 2009) | `MacBookPro5,2` | ^^ | | MacBook Pro (15-inch, Mid 2009) | `MacBookPro5,3`
`MacBookPro5,4` | ^^ | | MacBook Pro (13-inch, Mid 2009) | `MacBookPro5,5` | ^^ | | MacBook Pro (17-inch, Mid 2010) | `MacBookPro6,1` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108) | | MacBook Pro (15-inch, Mid 2010) | `MacBookPro6,2` | ^^ | | MacBook Pro (13-inch, Mid 2010) | `MacBookPro7,1` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021) | | MacBook Pro (13-inch, Early 2011)
MacBook Pro (13-inch, Late 2011) | `MacBookPro8,1` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108) | | MacBook Pro (15-inch, Early 2011)
MacBook Pro (15-inch, Late 2011) | `MacBookPro8,2` | ^^ | | MacBook Pro (17-inch, Early 2011)
| `MacBookPro8,3` | ^^ | | MacBook Pro (15-inch, Mid 2012) | `MacBookPro9,1` | - [Legacy Metal (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008) | | MacBook Pro (13-inch, Mid 2012) | `MacBookPro9,2` | ^^ | | MacBook Pro (Retina, 15-inch, Mid 2012)
MacBook Pro (Retina, 15-inch, Early 2013) | `MacBookPro10,1` | ^^ | | MacBook Pro (Retina, 13-inch, Late 2012)
MacBook Pro (Retina, 13-inch, Early 2013) | `MacBookPro10,2` | ^^ | | MacBook Pro (Retina, 13-inch, Late 2013)
MacBook Pro (Retina, 13-inch, Mid 2014) | `MacBookPro11,1` | ^^ | | MacBook Pro (Retina, 15-inch, Late 2013)
MacBook Pro (Retina, 15-inch, Mid 2014) | `MacBookPro11,2`
`MacBookPro11,3` | ^^ | | MacBook Pro (Retina, 15-inch, Mid 2015) | `MacBookPro11,4`
`MacBookPro11,5` | ^^ | | MacBook Pro (Retina, 13-inch, Early 2015) | `MacBookPro12,1` | ^^ | | MacBook Pro (13-inch, 2016, 2 Thunderbolt 3 ports) | `MacBookPro13,1` | ^^ | | MacBook Pro (13-inch, 2016, 4 Thunderbolt 3 ports) | `MacBookPro13,2` | ^^ | | MacBook Pro (15-inch, 2016) | `MacBookPro13,3` | ^^ | | MacBook Pro (13-inch, 2017, 2 Thunderbolt 3 ports) | `MacBookPro14,1` | - Native graphics support | | MacBook Pro (13-inch, 2017, 4 Thunderbolt 3 ports) | `MacBookPro14,2` | ^^ | | MacBook Pro (15-inch, 2017) | `MacBookPro14,3` | - [Legacy Metal (macOS 14+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008) | | MacBook Pro (13-inch, 2018, 4 Thunderbolt 3 ports)
MacBook Pro (13-inch, 2019, 4 Thunderbolt 3 ports) | `MacBookPro15,2` | - Supported by Apple | | MacBook Pro (15-inch, 2018)
MacBook Pro (15-inch, 2019) | `MacBookPro15,1`
`MacBookPro15,3` | ^^ | | MacBook Pro (13-inch, 2019, 2 Thunderbolt 3 ports) | `MacBookPro15,4` | ^^ | | MacBook Pro (16-inch, 2019) | `MacBookPro16,1`
`MacBookPro16,4` | ^^ | | MacBook Pro (13-inch, 2020, 4 Thunderbolt 3 ports) | `MacBookPro16,2` | ^^ | | MacBook Pro (13-inch, 2020, 2 Thunderbolt 3 ports) | `MacBookPro16,3` | ^^ | ### Mac mini | Model Name | Identifier | Additional info | | :--- | :--- | :--- | | Mac mini (Early 2009) | `Macmini3,1` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021) | | Mac mini (Mid 2010) | `Macmini4,1` | ^^ | | Mac mini (Mid 2011) | `Macmini5,1`
`Macmini5,2`
`Macmini5,3` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108) | | Mac mini (Late 2012) | `Macmini6,1`
`Macmini6,2` | - [Legacy Metal (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008) | | Mac mini (Late 2014) | `Macmini7,1` | ^^ | | Mac mini (Late 2018) | `Macmini8,1` | - Supported by Apple | ### iMac | Model Name | Identifier | Additional info | | :--- | :--- | :--- | | iMac (20-inch, Mid 2007)
iMac (24-inch, Mid 2007) | `iMac7,1` | - [Requires SSE4.1 CPU](https://lowendmac.com/2018/penryn-t9300-9500-cpu-upgrades-for-the-2007-imac/)
- [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021)
- Remove stock Bluetooth to prevent panics | | iMac (20-inch, Early 2008)
iMac (24-inch, Early 2008) | `iMac8,1` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021) | | iMac (20-inch, Early 2009)
iMac (24-inch, Early 2009)
iMac (20-inch, Mid 2009) | `iMac9,1` | - [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021)
- [Recommend upgrading to Metal GPU](https://forums.macrumors.com/threads/2011-imac-graphics-card-upgrade.1596614/?post=17425857#post-17425857) | | iMac (21.5-inch, Late 2009)
iMac (27-inch, Late 2009)| `iMac10,1` | ^^ | | iMac (27-inch, Late 2009) | `iMac11,1` | ^^ | | iMac (21.5-inch, Mid 2010) | `iMac11,2` | ^^ | | iMac (27-inch, Mid 2010) | `iMac11,3` | ^^ | | iMac (21.5-inch, Mid 2011)
iMac (21.5-inch, Late 2011) | `iMac12,1` | ^^ | | iMac (27-inch, Mid 2011) | `iMac12,2` | ^^ | | iMac (21.5-inch, Late 2012) | `iMac13,1` | - [Legacy Metal (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008) | | iMac (27-inch, Late 2012) | `iMac13,2` | ^^ | | iMac (21.5-inch, Early 2013) | `iMac13,3` | ^^ | | iMac (21.5-inch, Late 2013) | `iMac14,1` | ^^ | | iMac (27-inch, Late 2013) | `iMac14,2`
`iMac14,3` | ^^ | | iMac (21.5-inch, Mid 2014) | `iMac14,4` | ^^ | | iMac (Retina 5K, 27-inch, Late 2014)
iMac (Retina 5K, 27-inch, Mid 2015) | `iMac15,1` | ^^ | | iMac (21.5-inch, Late 2015) | `iMac16,1` | ^^ | | iMac (Retina 4K, 21.5-inch, Late 2015) | `iMac16,2` | ^^ | | iMac (Retina 5K, 27-inch, Late 2015) | `iMac17,1` | ^^ | | iMac (21.5-inch, 2017) | `iMac18,1` | - Native graphics support | | iMac (Retina 4K, 21.5-inch, 2017) | `iMac18,2` | ^^ | | iMac (Retina 5K, 27-inch, 2017) | `iMac18,3` | ^^ | | iMac (Retina 5K, 27-inch, 2019) | `iMac19,1` | - Supported by Apple | | iMac (Retina 4K, 21.5-inch, 2019) | `iMac19,2` | ^^ | | iMac (Retina 5K, 27-inch, 2020) | `iMac20,1`
`iMac20,2` | ^^ | | iMac Pro (2017) | `iMacPro1,1` | ^^ | ### Mac Pro | Model Name | Identifier | Additional info | | :--- | :--- | :--- | | Mac Pro (Early 2008) | `MacPro3,1` | - [Recommend upgrade to Metal GPU](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008)
- [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021)
- Remove stock Bluetooth to prevent panics | | Mac Pro (Early 2009) | `MacPro4,1` | - [Recommend upgrade to Metal GPU](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008)
- [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021) | | Mac Pro (Mid 2010)
Mac Pro (Mid 2012) | `MacPro5,1` | ^^ | | Mac Pro (Late 2013) | `MacPro6,1` | - [Legacy Metal (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008) | | Mac Pro (2019) | `MacPro7,1` | - Supported by Apple | ### Xserve | Model Name | Identifier | Additional info | | :--- | :--- | :--- | | Xserve (Early 2008) | `Xserve2,1` | - Recommend upgrade to Metal GPU
- [non-Metal GPU (macOS 11+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108)
- [USB 1.1 (macOS 13+)](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021) | Xserve (Early 2009) | `Xserve3,1` | ^^ | # Once you've verified your hardware is supported, head to [Download and build macOS Installers](./INSTALLER.md) --- ### MONTEREY DROP (`docs/MONTEREY-DROP.md`) # macOS Monterey With OpenCore Legacy Patcher v0.1.7 and newer, we've implemented beta macOS Monterey support for users. Please note that Apple has dropped a lot of hardware with this release as well as broken many of our previous patch sets. This page will be used to inform users regarding current issues and will be updated as new patch sets are developed and added to our patcher. ## Newly dropped hardware With Monterey, Apple continues their their somewhat ruthless march of dropping Intel hardware. This release saw the removal, and thus addition into OpenCore Legacy Patcher, of the following models: * iMac14,4 * iMac15,1 * MacBook8,1 * MacBookAir6,1 * MacBookAir6,2 * MacBookPro11,1 * MacBookPro11,2 * MacBookPro11,3 ::: details Model names * iMac (21.5-inch, Mid 2014) * iMac (Retina 5K, 27-inch, Late 2014) * MacBook (Retina, 12-inch, Early 2015) * MacBook Air (11-inch, Mid 2013) * MacBook Air (13-inch, Mid 2013) * MacBook Air (11-inch, Early 2014) * MacBook Air (13-inch, Early 2014) * MacBook Pro (Retina, 13-inch, Late 2013) * MacBook Pro (Retina, 15-inch, Late 2013) * MacBook Pro (Retina, 13-inch, Mid 2014) * MacBook Pro (Retina, 15-inch, Mid 2014) ::: All of these models now have support in OpenCore Legacy Patcher. ## Current Monterey Issues ### MacBookPro11,3 booting issue without Kepler acceleration Due to the display being routed through the NVIDIA Kepler card and macOS being rendered on the Intel iGPU, users have been experiencing issues booting without post-install patches applied ([see here for more info](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/522).) Currently the only workaround is to install the patches in safe mode, by holding down `Shift+Enter` when you select macOS in the OCLP boot picker. ## Previously Broken Hardware ::: details iMac15,1 5K Display Output Issue (Resolved in 0.3.2 and newer) * Documentation: * [5K iMac and UEFI: Fixing the dreaded output limitation](https://khronokernel.github.io/macos/2021/12/08/5K-UEFI.html) * Associated Github Issue: * [5k Output issues on iMac15,1 (27" 5k iMac - 2014) #359](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/359) ::: ::: details macOS 12.0 Beta 4 issue on 2012 to early 2013 machines (Resolved in 0.2.5 and newer) Currently in macOS 12.0 Beta 4, many Ivy Bridge Macs have experienced Bluetooth issues relating to their BCM20702 chipset. Currently the exact issue is unknown however is assumed to be a bug on Apple's end. Recommend downgrading to macOS 12.0 Beta 3 till resolved: * [12.0 Beta 3 (21A5284e) InstallAssistant (Direct)](http://swcdn.apple.com/content/downloads/02/08/071-63739-A_G5RYVW5JHT/dfz5gp3s0jm9vl7m30oewq141zkpv8edr8/InstallAssistant.pkg) * [12.0 Beta 3 (21A5284e) InstallAssistant (archive.org)](https://archive.org/details/12.0-21a5284e-beta-3) A temporary fix is to restart the BlueTool and bluetoothd process with each boot, note it may not work for all users: ```sh sudo killall -9 BlueTool bluetoothd ``` ::: ::: details Wireless Support Dropped (Resolved in 0.2.5 and newer) * Broadcom BCM94328, BCM94322 and Atheros Wireless Chipsets lost support The following models lost Wifi support in macOS Monterey due to their legacy Wireless chipset: * iMac12,x and older * Macmini3,1 and older * MacBook5,x and older * MacBookAir2,1 and older * MacBookPro7,1 and older * MacBookPro6,x is exempt * MacPro5,1 and older Note: BCM943224, BCM94331, BCM94360 and BCM943602 are still fully supported by OpenCore Legacy Patcher ::: ::: details Bluetooth Support Dropped (Resolved in 0.2.5 and newer) * BRCM2046 and BRCM2070 Bluetooth Chipsets lost support The following models lost Bluetooth support in macOS Monterey due to their legacy Bluetooth chipset: * iMac12,x and older * Macmini5,1 and older * MacBook7,1 and older * MacBookAir4,1 and older * MacBookPro8,1 and older * MacPro5,1 and older Note: Native BRCM20702 and BRCM20703 are still fully supported by OpenCore Legacy Patcher ::: details Dropped Firmwares Here are the firmwares macOS Monterey Dropped (previously located within IOBluetoothUSBDFU.kext): * 2046_820F.dfu * 2046_8210.dfu * 2046_8213.dfu * 2046_8215.dfu * 2046_8216.dfu * 2046_8217.dfu * 2070_821A.dfu * 2070_821B.dfu * 2070_8218.dfu * 20702_821D.dfu * 20702_821F.dfu * 20702_828A.dfu * 20702_828B.dfu * 20702_828C.dfu * 20702_8281.dfu * 20702_8286.dfu ::: ::: details Ivy Bridge iGPU Acceleration (Resolved in 0.1.7 and newer) * Intel HD4000 iGPUs lost support By default these machines require root volume patches to gain graphics acceleration in Monterey. OpenCore Legacy Patcher supports readding support however SIP can no longer be enabled due to root patching: * Macmini6,x * MacBookAir5,x * MacBookPro9,x * MacBookPro10,x ::: ::: details NVIDIA Kepler dGPU Acceleration (Resolved in 0.2.5 and newer) * NVIDIA Kepler dGPUs lost support By default these machines require root volume patches to gain graphics acceleration in Monterey. OpenCore Legacy Patcher supports readding support however SIP can no longer be enabled due to root patching: * MacBookPro9,1 * MacBookPro10,1 * MacBookPro11,3 * iMac13,x * iMac14,x ::: ::: details Non-Metal Acceleration (Resolved in 0.2.5 and newer) * Non-Metal GPUs no longer have working acceleration patches: * Intel Ironlake and Sandy Bridge iGPUs * NVIDIA Tesla and Fermi GPUs * AMD TeraScale 1 and 2 GPUs The following machines cannot gain graphics acceleration at all in Monterey, only basic framebuffer and brightness control (iMac8,1/9,1 and MacBook5,2 excluded): * iMac12,x and older * Macmini5,x and older * MacBook7,1 and older * MacBookAir4,x and older * MacBookPro8,x and older Note: iMac10,1 through iMac12,x can be upgraded with Metal GPUs, [see here for more info](https://forums.macrumors.com/threads/2011-imac-graphics-card-upgrade.1596614/) ::: --- ### PATCHEXPLAIN (`docs/PATCHEXPLAIN.md`) # Explaining the patches in OpenCore Legacy Patcher In our patcher, there are numerous patches used to ensure a stable system. Here, we're going to go over what patches are used and why we recommend or even require them. * [OpenCore Settings](#opencore-settings) * [Injected Kexts](#injected-kexts) * [On-Disk Patches](#on-disk-patches) ## OpenCore Settings Below is a rundown of the main logic that OpenCore Legacy Patcher uses to gain native support in macOS. Note that OpenCore's configuration is documented within [OpenCorePkg](https://github.com/acidanthera/OpenCorePkg) as well as on an online version provided by us: * [OpenCorePkg Online Docs](https://dortania.github.io/docs/latest/Configuration.html) ::: details Configuration Explanation ### ACPI -> Add * SSDT-CPBG * Reason: Resolves Kernel Panic on Arrandale Macs in early Big Sur builds * Logic: Disable dummy CPBG device in ACPI * Models: MacBookPro6,x and iMac11,x * SSDT-PCI * Reason: Patch Windows Audio support for Sandy and Ivy Bridge * Logic: Removes PCI0's 32-bit Allocation Limitation * Models: All Sandy and Ivy Bridge Macs, excluding MacPro6,1 * SSDT-DGPU * Reason: Allows for software based deMUX disabling dGPUs in 2011 MacBook Pros * Logic: Sends power down request to dGPU via ACPI * Models: MacBookPro8,2 and MacBookPro8,3 with dead dGPUs ### ACPI -> Patch * `EHCx` and `XHC1` Patches * Reason: Required for proper USB operation * Logic: Avoids USB maps of newer models attaching and breaking USB port functionality * Models: All models require when spoofing with Moderate or Advanced SMBIOS * `BUF0` to `BUF1` Patch * Reason: To be paired with SSDT-PCI * `_INI` to `XINI` Patch * Reason: To be paired with SSDT-DGPU ### Booter -> Patch * Reroute `HW_BID` to `OC_BID` * Reason: Allows macOS installers to be used on unsupported models * Logic: Reroutes Board ID macOS checks to custom variable * Models: All systems using VMM spoofing ### Booter -> Quirks * ForceBooterSignature * Reason: Required to ensure Hibernation support * Logic: Tricks boot.efi into thinking OpenCore is Apple's firmware * Models: All models require ### DeviceProperties -> Add * `PciRoot(0x0)/Pci(0x3,0x0)/Pci(0x0,0x0)` * `PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x0)` * Reason: Required to ensure Brightness Control works on upgraded iMacs * Logic: Sets AppleBackLight properties * Models: iMac11,x and iMac12,x with upgraded NVIDIA Metal GPUs * `PciRoot(0x0)/Pci(0x2,0x0)` * Reason: Disables internal GPU to fix sleep issues on upgraded iMacs * Logic: Tricks macOS into thinking iGPU is a generic PCI device * Models: iMac12,x with upgraded Metal GPUs ### Kernel -> Patch * SMC Patch * Reason: Required to avoid SMC Firmware updates * Logic: Patches out `smc-version` in AppleSMC.kext, requires SMC-Spoof.kext for full functionality * Models: All models require when spoofing SMBIOS * IOHIDFamily Patch * Reason: Required for HID peripheral support in macOS on older hardware * Logic: Tricks IOHIDFamily into thinking it's always booting recovery * Models: Penryn CPUs (Core2 series) * Force FileVault on Broken Seal Patch * Reason: Allow FileVault on root patched Macs * Logic: Forces APFS.kext to always return true on FileVault support * Models: Any model needing root patches * Disable Library Validation Enforcement Patch * Reason: non-Metal Root Volume Patches do not pass library validation tests * Logic: Forces Library Validation function to always return not required * Models: Non-Metal GPUs * SurPlus Patch * Reason: macOS 11.3-12.0.1 require systems to have RDRAND support in the CPU for stable boot * Logic: Forces RDRAND code to return predetermined value * Models: All pre-Ivy Bridge Macs * Reroute `kern.hv_vmm_present` Patch * Reason: Allows macOS to be installed and updated on unsupported hardware * Logic: Forces userspace to see system as Virtual Machine * Models: Any model using VMM spoofing ### Kernel -> Quirks * ThirdPartyDrives * Reason: Required to avoid Hibernation wake issues on 3rd party drives * Logic: Patches AppleAHCIPort.kext into support * Models: All models with standard SATA ports * PanicNoKextDump * Reason: Avoids kext dump on kernel panics, easier kernel debugging * Logic: Patches Kernel to not dump dump unnecessary info * Models: Only set when Verbose Boot is enabled by the user ### Misc -> Security * SecureBootModel * Reason: Required to allow native OS updates on T2 model spoofs * Logic: Sets T2's Secure Enclave Identifier * Models: All models required that spoof T2 model with minimal or higher ### NVRAM -> Add * `-v keepsyms=1 debug=0x100` * Reason: Used to see debug info of macOS's kernel and kexts, and avoids reboots on panic * Logic: Adds args to NVRAM * Models: Only set when Verbose Boot is enabled by the user * `-liludbgall` * Reason: Enables Lilu and plugin debug logging * Logic: Adds args to NVRAM * Models: Only set when Kext DEBUG is enabled by the user * `msgbuf=1048576` * Reason: Sets message buffer size to 1MB, ensures boot logs are retained * Logic: Adds args to NVRAM * Models: Only set when Kext DEBUG is enabled by the user * `agdpmod=pikera` * Reason: Fixes GPU switching on MacBookPro9,x * Logic: Adds args to NVRAM * Models: MacBookPro9,x * `shikigva=80 unfairgva=1` * `shikigva=128 unfairgva=1 -wegtree` * Reason: Fixes DRM support on models with upgraded AMD Metal GPUs * Logic: Adds args to NVRAM * Models: Models with upgraded AMD Metal GPUs * `-revasset` * Reason: Enables Content Caching when using VMM spoofing * Logic: Adds args to NVRAM * Models: Any model using VMM spoofing * `amfi=0x80` * Reason: Disables Apple Mobile File Integrity to allow for root patches * Logic: Adds args to NVRAM * Models: Any model that requires unsigned root patches ### UEFI -> ProtocolOverrides * GopPassThrough * Reason: Used for proper output on machines with UGA firmware but GOP GPU * Logic: Provide GOP protocol instances on top of UGA protocol instances * Models: MacPro3,1, iMac7,1-8,1 ::: ## Injected Kext Below is an explanation of what Kexts OpenCore Legacy Patcher will inject into memory on boot-up. ::: details Injected Kext Explanation ### Acidanthera * Lilu * Reason: Patching engine for other kexts * Models: All models require * WhateverGreen * Reason: Patches GPU Frameworks and kext to ensure proper support * Models: All models require when spoofing or have non-stock GPU * CPUFriend * Reason: Patches IOx86PlatformPlugin to restore previous CPU profiles * Models: All models using minimal or higher spoofing * AirportBrcmFixup * Reason: Patches IO80211 and co to fix networking support for unsupported cards, and fix bugs on native ones as well (ie. random degraded network performance) * Models: BCM943224, BCM94331, BCM94360 and BCM943602 * BlueToolFixup * Reason: Patches BlueTool to enable bluetooth functionality on Monterey * Models: All models with pre-BCM94360 wireless cards or 3rd-party chipsets * Bluetooth-Spoof * Reason: Injects extra data into certain bluetooth chipsets for recognition by the system * Models: Models with the BCM2070 or BCM2046 chipsets * FeatureUnlock (Night Shift) * Reason: Patches CoreBrightness.framework to enable Night Shift on unsupported models * Models: 2011 or older * FeatureUnlock (Sidecar/AirPlay) * Reason: Patches SidecarCore.framework and AirPlaySupport.framework to enable Sidecar and AirPlay to Mac on unsupported models * Models: All models with Metal capable GPUs * RestrictEvents * Reason: Disables memory errors on MacPro7,1 * Models: Mac Pros and Xserves * CryptexFixup * Reason: Installs non AVX2.0 Cryptex on non AVX2.0 CPUs * Models: All CPUs Ivy Bridge and older * AutoPkgInstaller * Reason: Allows for automatic root patching * NVMeFix * Reason: Fixes 3rd party NVMe support * RSRHelper * Reason: Fixes Rapid Security Response Support on root patched installs * ### Ethernet * nForceEthernet * Reason: Inject old NVIDIA Ethernet kext to resolve networking in Catalina and newer * Models: 2010 and older NVIDIA Ethernet require * MarvelYukonEthernet * Reason: Inject old Marvel Ethernet kext to resolve networking in Catalina and newer * Models: 2008 and older Marvel Ethernet require * CatalinaBCM5701Ethernet * Reason: Inject old Broadcom Ethernet kext to resolve networking in Big Sur * Logic: Patch out conflicting symbols to not collide existing BCM5701Ethernet * Models: 2011 and older Broadcom Ethernet require * Intel82574L * Reason: Resolves Ethernet Support on MacPros * Models: MacPro3,1 - 5,1 * CatalinaIntelI210Ethernet * Reason: Fixes Intel i210/i225 NIC support on pre-Ivy Macs * AppleIntel8254XEthernet * Reason: Resolves Ethernet Support on MacPros * Models: MacPro3,1 - 5,1 ### Firewire * IOFireWireFamily * Reason: Allows for FireWire Boot Support * IOFireWireSBP2 * Reason: Allows for FireWire Boot Support * IOFireWireSerialBusProtoColTransport * Reason: Allows for FireWire Boot Support ### Maps * USBMap * Reason: Inject old USB map profiles to fix USB * Models: All models require when spoofing moderate or higher, as well as pre-2012 models ### SSE * AAMouSSE * Reason: Translates SSE4.2 instructions to compatible code for SSE4,1 CPUs, required for AMD Metal drives * Models: MacPro3,1 * telemetrap * Reason: Ensures telemetry.plugin doesn't run, required for SSE4,1 CPUs * Models: Penryn CPUs ### Wifi * IO80211ElCap * Reason: Re-inject WiFi drivers from El Capitan * Models: BCM94328, BCM94322 and Atheros chipsets * corecaptureElCap.kext * Reason: Re-inject WiFi drivers from El Capitan * Models: BCM94328, BCM94322 and Atheros chipsets ### Misc * AppleBackLightFixup * Reason: Patch AppleBacklight for iMacs with NVIDIA Metal GPU upgrades * Models: iMac11,x, iMac12,x with upgraded NVIDIA Metal GPUs * AppleIntelPIIXATA * Reason: Fix IDE support on MacPro3,1 * Models: MacPro3,1 * AppleIntelMCEDisabler * Reason: Fix dual socket support in Catalina and newer * Models: Mac Pros and Xserves * SMC-Spoof * Reason: Spoofs SMC version to 9.9999 * Models: All models require when spoofing minimal or higher * AppleRAIDCard * Adds AppleRaidCard Support for Xserves * AMDGPUWakeHandler * Reason: Adds Software Based Demux for 2011 15/17 Macbook Pros * AppleIntelCPUPowerManagement and AppleIntelCPUPowerManagementClient * Reason: Restores Ivy Bridge and older CPU Power Management * AppleUSBTopCase * Reason: Restore USB Keyboard support on Mac OS Ventura * AppleUSBMultitouch and AppleUSBTrackpad * Reason: Restore USB Trackpad support on Mac OS Ventura * ASPP-Override * Reason: Forces ACPI_SMC_PlatformPlugin to outmatch X86PlatformPlugin and disable firmware throttling * BacklightInjector * Reason: Fixes Brightness in iMacs with upgraded GPUs * BigSurSDXC * Reason: Restores SDXC Support in Pre Ivy-Bridge Macs * Bluetooth-spoof * Reason: Spoofs legacy Bluetooth to work on Monterey and newer * Innie * Reason: Makes all PCIe drives appear internal * Models: MacPro3,1 and newer & Xserve3,1 and newer * KDKlessWorkaround * Reason: Helps with Mac os updates on KDKless patched systems * LegacyUSBVieoSupport * Reason: Fixes Legacy USB iSight support * MonteAHCIPort * Reason: Fixes SSD support for stock SSD found in MacBookAir6,x * NoAVXFSCompressionTypeZlib * Reason: Prevents AVXFSCompressionTypeZlib crash on pre AVX1.0 systems in 12.4+ * SimpleMSR * Reason: Disables BD PROCHOT to prevent firmware throttling on Nehalem+ MacBooks * LegacyKeyboardInjector * Reason: Fixes function keys on MacBook5,2 ::: ## On-Disk Patches Unfortunately certain on-disk patches are required to achieve full functionality. Below is a breakdown of patches supported ::: details Audio Patches (11.0+) ### Extensions * AppleHDA * Reason: Re-add El Capitan's AppleHDA to achieve audio support * Models: iMac7,1 and iMac8,1 ::: ::: details Legacy Wireless Patches (12.0+) Applicable for BCM94328, BCM94322 and Atheros Wifi cards ### CoreServices * WiFiAgent.app ### /usr/libexec * airportd ::: ::: details NVIDIA Kepler Graphics Acceleration Patches (12.0+) ### Extensions * GeForce.kext * GeForceAIRPlugin.bundle * GeForceGLDriver.bundle * GeForceMTLDriver.bundle * GeForceVADriver.bundle * NVDAGF100Hal.kext * NVDAGK100Hal.kext * NVDAResman.kext * NVDAStartup.kext ### Frameworks * OpenCL (libCLVMNVPTXPlugin.dylib, NVPTX.dylib) * Reason: Re-add Kepler hardware acceleration support * Metal * Reason: 3802 based GPU's broken by 13.3, requiring a Metal downgrade to 13.2.1 ### PrivateFrameworks * MTLCompiler * Reason: 3802 based GPU's broken by 13.3, requiring a MTLCompiler downgrade to 13.2.1 * GPUCompiler * Reason: 3802 based GPU's broken by 13.3, requiring a GPUCompiler downgrade to 13.2.1 ::: ::: details Intel Ivy Bridge Graphics Acceleration Patches (12.0+) ### Extensions * AppleIntelIVBVA.bundle * AppleIntelFramebufferCapri.kext * AppleIntelGraphicsShared.bundle * AppleIntelHD4000Graphics.kext * AppleIntelHD4000GraphicsGLDriver.bundle * AppleIntelHD4000GraphicsMTLDriver.bundle * AppleIntelHD4000GraphicsVADriver.bundle ### PrivateFrameworks * AppleGVA/AppleGVACore * Reason: Enable DRM support * MTLCompiler * Reason: 3802 based GPU's broken by 13.3, requiring a MTLCompiler downgrade to 13.2.1 * GPUCompiler * Reason: 3802 based GPU's broken by 13.3, requiring a GPUCompiler downgrade to 13.2.1 ### Frameworks * OpenCL (libCLVMIGILPlugin.dylib) * Reason: Re-add Ivy Bridge hardware acceleration support * WebKit (com.apple.WebProcess.sb) * Reason: Re-add Ivy Bridge Safari rendering support * Metal * Reason: 3802 based GPU's broken by 13.3, requiring a Metal downgrade to 13.2.1 ::: ::: details Intel Haswell Graphics Acceleration Patches (13.0+) ### Extensions * AppleIntelFramebufferAzul.kext * AppleIntelHD5000Graphics.kext * AppleIntelHD5000GraphicsGLDriver.bundle * AppleIntelHD5000GraphicsMTLDriver.bundle * AppleIntelHD5000GraphicsVADriver.bundle * AppleIntelHSWVA.bundle * AppleIntelGraphicsShared.bundle ### Frameworks * Metal * Reason: 3802 based GPU's broken by 13.3, requiring a Metal downgrade to 13.2.1 ### PrivateFrameworks * MTLCompiler * Reason: 3802 based GPU's broken by 13.3, requiring a MTLCompiler downgrade to 13.2.1 * GPUCompiler * Reason: 3802 based GPU's broken by 13.3, requiring a GPUCompiler downgrade to 13.2.1 ::: ::: details Intel Broadwell Graphics Acceleration Patches (13.0+) ### Extensions * AppleIntelBDWGraphics.kext * AppleIntelBDWGraphicsFramebuffer.kext * AppleIntelBDWGraphicsGLDriver.bundle * AppleIntelBDWGraphicsMTLDriver.bundle * AppleIntelBDWGraphicsVADriver.bundle * AppleIntelBDWGraphicsVAME.bundle * AppleIntelGraphicsShared.bundle ::: ::: details Intel Skylake Graphics Acceleration Patches (13.0+) ### Extensions * AppleIntelSKLGraphics.kext * AppleIntelSKLGraphicsFramebuffer.kext * AppleIntelSKLGraphicsGLDriver.bundle * AppleIntelSKLGraphicsMTLDriver.bundle * AppleIntelSKLGraphicsVADriver.bundle * AppleIntelSKLGraphicsVAME.bundle * AppleIntelGraphicsShared.bundle ::: ::: details AMD Legacy Vega Graphics Acceleration Patches (13.0+) ### Extensions * AMDRadeonX5000.kext * AMDRadeonVADriver2.bundle * AMDRadeonX5000GLDriver.bundle * AMDRadeonX5000MTLDriver.bundle * AMDRadeonX5000Shared.bundle * AMDShared.bundle ::: ::: details AMD Legacy Polaris Graphics Acceleration Patches (13.0+) ### Extensions * AMDRadeonX4000.kext * AMDRadeonX4000HWServices.kext * AMDRadeonVADriver2.bundle * AMDRadeonX4000GLDriver.bundle * AMDMTLBronzeDriver.bundle * AMDShared.bundle ::: ::: details AMD Legacy GCN Graphics Acceleration Patches ### Extensions * AMD7000Controller.kext * AMD8000Controller.kext * AMD9000Controller.kext * AMD9500Controller.kext * AMD10000Controller.kext * AMDRadeonX4000.kext * AMDRadeonX4000HWServices.kext * AMDFramebuffer.kext * AMDSupport.kext * AMDRadeonVADriver.bundle * AMDRadeonVADriver2.bundle * AMDRadeonX4000GLDriver.bundle * AMDMTLBronzeDriver.bundle * AMDShared.bundle ::: ::: details non-Metal Graphics Acceleration Patches (11.0+) ### General Patches * IOSurface.kext * Reason: Fixes immediate logout on login * Logic: Downgrade to Catalina IOSurface * Note: For AMD and Intel, additional `addMemoryRegion/removeMemoryRegion` patch added changing the first conditional jump to non conditional jump * At Offset `0xdb52` and `0xdbc6`, replace following bytes with `0xeb` ### Dropped Acceleration Binaries * NVIDIA Binaries * GeForceGA.bundle * GeForceTesla.kext * Skip IOFree Panic - Mojave+ * At Offset `0x5CF9A` replace following bytes with `0xEB` * Avoids `addMemoryRegion/removeMemoryRegion` calls * At Offset `0x5527` and `0x77993`, replace following bytes with `0x909090909090` * GeForceTeslaGLDriver.bundle * GeForceTeslaVADriver.bundle * NVDANV50HalTesla.kext * NVDAResmanTesla.kext * 0x1ea59a - 0x1ea5b3: nop * Replace VSLGestalt to IOLockLock or any other known symbol of the same length. * NVIDIA Web Drivers Binaries * GeForceWeb.kext * NVDAGF100HalWeb.kext * NVDAGK100HalWeb.kext * NVDAGM100HalWeb.kext * NVDAGP100HalWeb.kext * NVDAResmanWeb.kext * NVDAStartupWeb.kext * GeForceTeslaWeb.kext * NVDANV50HalTeslaWeb.kext * NVDAResmanTeslaWeb.kext * Reason: Allows for non-Metal Acceleration for NVIDIA Maxwell and Pascal GPUs * AMD/ATI Binaries * AMD2400Controller.kext * AMD2600Controller.kext * AMD3800Controller.kext * AMD4600Controller.kext * AMD4800Controller.kext * AMD5000Controller.kext * AMD6000Controller.kext * AMDFramebuffer.kext * AMDLegacyFramebuffer.kext * AMDLegacySupport.kext * AMDRadeonVADriver.bundle * AMDRadeonVADriver2.bundle * AMDRadeonX3000.kext * AMDRadeonX3000GLDriver.bundle * AMDShared.bundle * AMDSupport.kext * ATIRadeonX2000.kext * ATIRadeonX2000GA.plugin * ATIRadeonX2000GLDriver.bundle * ATIRadeonX2000VADriver.bundle * Intel 5th Gen Binaries * AppleIntelFramebufferAzul.kext * AppleIntelFramebufferCapri.kext * AppleIntelHDGraphics.kext * AppleIntelHDGraphicsFB.kext * AppleIntelHDGraphicsGA.plugin * AppleIntelHDGraphicsGLDriver.bundle * AppleIntelHDGraphicsVADriver.bundle * Intel 6th Gen Binaries * AppleIntelHD3000Graphics.kext * AppleIntelHD3000GraphicsGA.plugin * AppleIntelHD3000GraphicsGLDriver.bundle * AppleIntelHD3000GraphicsVADriver.bundle * AppleIntelSNBGraphicsFB.kext * Board ID Patch * Replace original Board ID with updated model * AppleIntelSNBVA.bundle ### Frameworks * CoreDisplay.framework * Logic: Copied from Mojave, heavy modifications/shims * IOSurface.framework * OpenGL.framework * Logic: Copied from Mojave ### PrivateFrameworks * GPUSupport.framework * Logic: Copied from Mojave * SkyLight.framework * Logic: Copied from Mojave, heavy modifications/shims ::: --- ### POST INSTALL (`docs/POST-INSTALL.md`) # Post-Installation * [Booting without USB drive](#booting-without-usb-drive) * [Booting seamlessly without Boot Picker](#booting-seamlessly-without-boot-picker) * [SIP settings](#sip-settings) * [Applying Post Install Volume Patches](#applying-post-install-volume-patches) ## Booting without USB drive Once you've installed macOS through OpenCore, you can boot up and go through the regular install process. To boot without the USB drive plugged in is quite simple: * Download OpenCore Legacy Patcher * Change Patcher settings as you'd like * Build OpenCore again * Install OpenCore to internal drive * Reboot holding Option, and select the internal EFI And voila! No more USB drive required. If you're having issues with undetected internal disk, refer to [Internal disk missing when building OpenCore](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOT-APP.html#internal-disk-missing-when-building-opencore) for troubleshooting. ## Booting seamlessly without Boot Picker To do this, run the OpenCore Patcher and head to Patcher Settings, then uncheck "Show OpenCore Bootpicker" on the Build tab:
GUI Settings ShowPicker
Once you've toggled it off, build your OpenCore EFI once again and install to your desired drive. Now to show the OpenCore selector, you can simply hold down the "ESC" key while clicking on EFI boot, and then you can release the "ESC" key when you see the cursor arrow at the top left. ## SIP settings SIP, or System Integrity Protection, needs to be lowered on systems where root patching is required to patch data on disk. This will vary between OS versions and the model in question. OCLP by default will determine the proper SIP options for the OS version and Mac model, in most cases the user has no need to touch these settings. :::warning If you're unsure whether you should change the SIP settings, leave them as-is. Systems where you have already ran the Post Install Root Patching cannot enable SIP without potentially breaking the current install. ::: | SIP Enabled | SIP Lowered (OCLP default) | SIP Disabled | | :--- | :--- | :--- | | | | | The guide in the dropdown below explains how the SIP settings work in OCLP, where lowered SIP is needed and where full SIP could be enabled. ::: details Configuring SIP manually (click to expand) SIP settings can be accessed from the Security tab shown in the images. To change SIP settings, make the changes here, return in main menu and rebuild OpenCore using the first option. In the cases where SIP can be enabled, manually enabling it is needed. Easiest way to check whether you can fully enable SIP is the "Post Install Root Patch" section, if that section tells your system doesn't need patches (or you don't install the patches e.g. in case you don't need WiFi on a Mac Pro with upgraded GPU running Monterey) then it is safe to assume full SIP can be enabled. **Ventura and newer** All unsupported systems require lowered SIP. **Monterey** Majority of unsupported systems from 2013 onward can enable full SIP. Pre-2012 systems, also known as "non-Metal", as well as NVIDIA Kepler and Intel HD 4000 GPUs require lowered SIP. Mac Pros also require lowered SIP for stock WiFi cards and stock GPUs (due to root patching) but if you do not need WiFi (or you plan to upgrade it) and you're running on an upgraded GPU, there is no need for root patching and as such SIP can be fully enabled. **Big Sur** All Metal capable systems from 2012 onward (incl. NVIDIA Kepler and Intel HD 4000) as well as Mac Pros with upgraded GPU can run with full SIP enabled. Non-Metal systems still require lowered SIP. ::: ## Applying Post Install Volume Patches Post Install Volume Patches, sometimes also called root patches, are patches that have to be installed to disk for some older Macs to gain back functionality. These patches include things such as: - Graphics drivers - WiFi drivers - Bluetooth drivers - Touchbar / T1 drivers - Built-in camera (iSight) drivers - USB 1.1 drivers - Other patches for compatibility with older drivers OCLP will automatically root patch your system if the USB install media was created within OCLP and the proper model was selected before installer creation. If you did not use OCLP to create the USB drive or autopatching failed, you will need to download OCLP manually and install root patches, since the application will be missing if autopatching wasn't successful. **Root patches will be wiped by macOS updates and have to be reinstalled after each update.** OCLP will prompt to install these patches after macOS updates or whenever patches are not detected on the system. The USB installer method can also be used to install future updates, utilizing the autopatching process and avoiding the manual patching which is required when updating through System Settings. In the Post-Install Menu, you can see whether applicable patches have been installed, including the date and version the system was root patched with. ::: warning Important In some cases OCLP may require packages to be obtained from the internet, such as KDK or MetallibSupportPkg if they do not already exist on the system. In these cases OCLP may only install the WiFi driver on first patch run to ensure you can connect to the internet, which means no graphics acceleration after reboot. Root patching has to be ran again manually to install the rest of the required patches after internet connection is established to obtain the required packages. You can also utilize Ethernet, which should ensure that all patches will be installed at once. [Check the affected systems and GPUs from below.](#packages-requiring-networking) ::: :::warning If you need to use Migration Assistant to bring over data to your new macOS install, [refer to the guide to do so here.](https://dortania.github.io/OpenCore-Legacy-Patcher/TIMEMACHINE.html) ::: | Automatic install prompt | Status | Listing Patches | Patching Finished | | :--- | :--- | :--- | :--- | | | | | | You can install and revert Root Patching manually from the app. ### Packages requiring networking #### MetallibSupportPkg Required for Ivy Bridge, Haswell and NVIDIA Kepler based systems (3802) running Sequoia or newer. You can download it manually from the following link: * [MetallibSupportPkg](https://github.com/dortania/MetallibSupportPkg/releases) **Make sure the build matches exactly the OS version you're using.** ::: details Full GPU model list requiring MetallibSupportPkg (click to expand) * NVIDIA * Kepler (GTX 600 - 700 series, Quadro K-series) * Intel * Ivy Bridge (HD 4000 series) * Haswell (Iris/HD 4000-5000 series) ::: #### KDK / Kernel Debug Kit Macs with AMD Legacy GCN GPUs (ie. Metal) running Ventura or newer require Apple's Kernel Debug Kit to start root patching. You can manually download the KDK from the following link: * [KDKSupportPkg](https://github.com/dortania/KdkSupportPkg/releases) Grab the Kernel Debug Kit whose version is closest to the OS you installed and install it to the machine. :::details Macs and GPUs requiring KDK (click to expand) GPUs: * Radeon HD 7000 series * Radeon R9 series * FirePro D300/D500/D700 Mac models with GCN GPUs: * iMac 2014 - 2015 (iMac15,1 - 17,1) * Mac Pro 2013 (MacPro6,1) * MacBook Pro 2015 15", dGPU version (MacBookPro11,5) Upgraded Macs: * Mac Pro 2008 - 2012 (MacPro3,1 - 5,1) if upgraded with AMD GCN GPU. * iMac 2009 - 2011 (iMac10,1 - 12,1) if upgraded with AMD GCN GPU. ::: ### Other information Below entries represent GPUs no longer natively supported, ie. requiring root volume patching with OpenCore Legacy Patcher: :::details GPUs requiring patching in different macOS versions AMD Navi (RX 5000 - 6000 series) GPUs are non-functional in Mac Pro 2008 to 2012 using Ventura and newer due to lack of AVX2 support. **Ventura/Sonoma/Sequoia** * NVIDIA: * Tesla (8000 - 300 series) * Kepler (600 - 800 series) * AMD: * TeraScale (2000 - 6000 series) * GCN 1-3 (7000 - R9 series) * Polaris (RX 4xx/5xx series, if CPU lacks AVX2) * Intel: * Iron Lake * Sandy Bridge (2000 - 3000 series) * Ivy Bridge (4000 series) * Haswell (4400, 4600, 5000 series) * Broadwell (6000 series) * Skylake (500 series) **Monterey** * NVIDIA: * Tesla (8000 - 300 series) * Kepler (600 - 800 series) * AMD: * TeraScale (2000 - 6000 series) * Intel: * Iron Lake * Sandy Bridge (2000 - 3000 series) * Ivy Bridge (4000 series) **Big Sur** * NVIDIA: * Tesla (8000 - 300 series) * AMD: * TeraScale (2000 - 6000 series) * Intel: * Iron Lake * Sandy Bridge (2000 - 3000 series) ::: :::details Wireless Cards requiring patching in macOS Monterey * Broadcom: * BCM94328 * BCM94322 * Atheros ::: --- ### PROCESS (`docs/PROCESS.md`) # Background process OpenCore Legacy Patcher utilizes a background process to: - Check for mismatched configurations and warn the user (e.g. installed MacBookPro11,1 config on MacBookPro11,5) - Monitor the status of installed Root Patches and OpenCore - Ask you to install Root Patches in case they aren't detected (typically after an update) - Check whether OpenCore is being booted from USB drive or internal drive - Ask you to install OpenCore on the internal disk in case booted from USB - React to upcoming updates requiring a new KDK to be downloaded, starting KDK download automatically It is recommended to keep the background process enabled for smoothest functionality. e.g. to try and avoid failed patching when new KDK is not found. If you decide to disable the background process, the KDK installation for each update has to be done manually. OCLP is also unable to detect Root Patches on boot, meaning manually opening the app and root patching is required. ::: warning Note: In some cases macOS may report background process being added by "Mykola Grymalyuk", this happens due to a macOS bug where sometimes the developer name who sent the app for notarization is shown instead of the application name. Dortania cannot do anything about this. ::: --- ### SEQUOIA DROP (`docs/SEQUOIA-DROP.md`) # macOS Sequoia Another year, another release. This time Apple dropped surprisingly few amount of Macs. With the release of OpenCore Legacy Patcher 2.0.0, early support for macOS Sequoia has been implemented. ## Newly dropped hardware * MacBookAir8,1 : MacBook Air (2018) * MacBookAir8,2 : MacBook Air (2019) ## Current status OpenCore Legacy Patcher 2.0.0 supports Sequoia for the models below, however some challenges remain. You can find information about them further down this page. Unfortunately due to T2 related problems, the recently dropped MacBookAir8,x models cannot be supported at this time. We have made some progress on this issue, but panics are still occurring and there is still a significant amount of development work to do before T2 machines may even get to the install screen. We cannot provide any estimate on when T2 machines will be supported. [More information here.](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1136) ## Non-functional features On majority of patched Macs, iPhone Mirroring and Apple Intelligence won't be functional. iPhone Mirroring requires T2 for attestation and Apple Intelligence requires an NPU only found in Apple Silicon, the patcher is unable to provide a fix for these as they're hardware requirements. ## Issues * [Dual socket CPUs with Mac Pros and Xserve](#dual-socket-cpus-with-mac-pro-2008-and-xserve-2008) * [T2 Security chip](#t2-security-chip) * [USB 1.1 (OHCI/UHCI) Support](#usb-1-1-ohci-uhci-support) * [Graphics support and issues](#graphics-support-and-issues) ### Dual socket CPUs with Mac Pro 2008 and Xserve 2008 Booting Sequoia on Mac Pro 2008 (MacPro3,1) or Xserve 2008 (Xserve2,1) with more than 4 cores will cause Sequoia to panic. OpenCore Legacy Patcher will automatically disable additional cores. This is due to the dual socket nature of the machine, and likely some firmware/ACPI table incompatibility. **If building OpenCore for older OS, this limitation can be disabled in Settings -> Build -> "MacPro3,1/Xserve2,1 Workaround".** ::: warning Note Dual booting Sequoia and older will not be possible with all cores enabled due to reasons described before. In these cases you will be limited to 4 cores. ::: ### T2 security chip The current biggest issue we face with supporting the MacBookAir8,x (2018/19) series is the T2 chip's lack of communication when booted through OpenCorePkg. What happens when one of these units boots through OpenCorePkg is that AppleKeyStore.kext panics due to timeouts with the T2 chip: ``` "AppleKeyStore":3212:0: sks timeout strike 18 "AppleKeyStore":3212:0: sks timeout strike 19 "AppleKeyStore":3212:0: sks timeout strike 20 panic(cpu 0 caller 0xffffff801cd12509): "AppleSEPManager panic for "AppleKeyStore": sks request timeout" @AppleSEPManagerIntel.cpp:809 ``` This affects not only macOS Sequoia, but macOS Ventura and Sonoma are confirmed to have the same issue. Thus an underlying problem with the MacBookAir8,x's firmware where it is not happy with OpenCorePkg. * MacBookPro15,2, MacBookPro16,2 and Macmini8,1 do not exhibit these issues in local testing * MacPro7,1 does seem to surprisingly based on reports: [MacPro7,1 - OpenCorePkg](https://forums.macrumors.com/threads/manually-configured-opencore-on-the-mac-pro.2207814/post-29418464) * Notes from this report were unsuccessful locally: [Cannot boot MacPro7,1 #1487](https://github.com/acidanthera/bugtracker/issues/1487) We have made some progress on this issue, but panics are still occurring and there is still a significant amount of development work to do before T2 machines may even get to the install screen. We cannot provide any estimate on when T2 machines will be supported. ### USB 1.1 (OHCI/UHCI) Support For Penryn systems, pre-2013 Mac Pros and Xserve, USB 1.1 support was outright removed in macOS Ventura, therefore this applies all the way to Sequoia. While USB 1.1 may seem unimportant, it handles many important devices on your system. These include: * Keyboard and Trackpad for laptops * IR Receivers * Bluetooth Refer to [the troubleshooting page](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOT-HARDWARE.html#keyboard-mouse-and-trackpad-not-working-in-installer-or-after-update) on how to workaround this issue. ### Graphics support and issues This build includes both Legacy Metal and non-Metal patches for macOS Sequoia. Refer to the following links for more information about Legacy Metal and non-Metal support and their respective issues. * [Legacy Metal](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008) * [Non-Metal](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108) --- ### SONOMA DROP (`docs/SONOMA-DROP.md`) # macOS Sonoma *Well here we are again, it's always such a pleasure~* Apple has yet again dropped a bunch of models, continuing their journey on discontinuing Intel Macs. With the release of OpenCore Legacy Patcher 1.0.0, early support for macOS Sonoma has been implemented. ## Newly dropped hardware * MacBook10,1: MacBook (Retina, 12-inch, 2017) * MacBookPro14,1: MacBook Pro (13-inch, 2017, Two Thunderbolt 3 ports) * MacBookPro14,2: MacBook Pro (13-inch, 2017, Four Thunderbolt 3 Ports) * MacBookPro14,3: MacBook Pro (15-inch, 2017) * iMac18,1: iMac (21.5-inch, 2017) * iMac18,2: iMac (Retina 4K, 21.5-inch, 2017) * iMac18,3: iMac (Retina 5K, 27-inch, 2017) ## Current status OpenCore Legacy Patcher 1.0.0 supports Sonoma for all models below, however some challenges remain. You can find information about them further down on this page. ## Issues * [Bluetooth](#bluetooth) * [T1 Security chip](#t1-security-chip) * [USB 1.1 (OHCI/UHCI) Support](#usb-1-1-ohci-uhci-support) * [Graphics support and issues](#graphics-support-and-issues) ### Bluetooth Sometimes Bluetooth may not work after boot on pre-2012 models. Running NVRAM reset can alleviate it. Dual boots may also bring the issue back even after the reset. ### T1 Security chip **Resolved in 1.1.0 and newer, original explainer below** ::: details Support for the T1 Security chip Sonoma has removed support for T1 chips found in most 2016 and 2017 Macs. Therefore on these systems, the following will not function: * Enable or disable FileVault * Open the Password Settings window * Add fingerprints (if upgrading, existing fingerprints will be deleted) * Add cards to Apple Pay [More information here](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1103) ::: ::: warning Note that erasing the entire drive will remove the T1 firmware and it won't be reinstalled. Refer to [troubleshooting](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOT-HARDWARE.html#no-t1-functionality-after-installing-sonoma-or-newer) for more information. ::: ### USB 1.1 (OHCI/UHCI) Support For Penryn systems, pre-2013 Mac Pros and Xserve, USB 1.1 support was outright removed in macOS Ventura and naturally this continues in Sonoma. While USB 1.1 may seem unimportant, it handles many important devices on your system. These include: * Keyboard and Trackpad for laptops * IR Receivers * Bluetooth Refer to [the troubleshooting page](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOT-HARDWARE.html#keyboard-mouse-and-trackpad-not-working-in-installer-or-after-update) on how to workaround this issue. ### Graphics support and issues This build includes both Legacy Metal and non-Metal patches for macOS Sonoma. Refer to the following links for more information about Legacy Metal and non-Metal support and their respective issues. * [Legacy Metal](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008) * [Non-Metal](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108) --- ### START (`docs/START.md`) # What is OpenCore? OpenCore is a sophisticated boot loader used to inject and patch data in memory, instead of on disk. This means that we're able to achieve a near-native experience on many unsupported Macs. We recommend viewing the [OpenCore Patcher Terminology Page](./TERMS.md) if you have questions. For troubleshooting, see our troubleshooting pages below or join the [OpenCore Patcher Paradise Discord Server.](https://discord.gg/rqdPgH8xSN) - [Application troubleshooting](./TROUBLESHOOT-APP.md) - [Booting, installer and other troubleshooting](./TROUBLESHOOT-MISC.md) - [Non-Metal troubleshooting](./TROUBLESHOOT-NONMETAL.md) - [Hardware troubleshooting](./TROUBLESHOOT-HARDWARE.md) ## How do I get started? 1. Read the [FAQ](./FAQ.md) for application requirements and other information. 2. Check that your model is supported from the [Supported Models](./MODELS.md) page. 3. Once you've verified your model is supported, you can jump into the process in [Download and build macOS Installer](./INSTALLER.md) --- ### TERMS (`docs/TERMS.md`) # OpenCore Patcher Terminology With OpenCore Legacy Patcher, we use a lot of different terms to refer to hardware including `SSE4.1`, `32-Bit Firmware`, etc. This page is to help users understand what all these confusing words mean. # Terminology Term | Description --- | --- **macOS** | Apple's own UNIX based OS used for Mac machines and is "What makes a Mac a Mac". **Windows** | Microsoft's proprietary OS that is used and supported on a wide range of devices **Linux** | Family of open source Unix-like operating systems based on the Linux kernel, an operating system kernel first released on September 17, 1991, by Linus Torvalds. Linux is typically packaged in a Linux distribution. Note that while macOS and Linux may be UNIX-based, they're vastly different. **Bootloader** | Piece of software that loads an OS, usually made by the OS creators. OpenCore is technically not a bootloader per se (see boot manager explanation down below). Apple's Boot.efi would be the actual boot loader in a Mac. **Boot Manager** | Piece of software that manages bootloaders – we have many of these: Clover, systemd-boot, OpenCore, rEFInd, rEFIt... These are generally seen as prepping the system for the actual boot loader. --- Term | Description --- | --- **OpenCore** | The new hotness on the scene, made with security in mind by the [Acidanthera team](https://github.com/acidanthera), has faster booting and lighter weight than previous boot managers. Supports many native Mac features such as SIP, FileVault, Secure Boot, etc **ACPI** | Tables defined in your firmware defining your hardware and different methods, tied directly to how IOKit/IOService handles device setup **NVRAM** | Non-volatile storage, where many variables are stored including default boot options, Hibernation keys, Secure Boot information, etc --- Term | Description --- | --- **XNU** | Also known as **X** is **N**ot **U**nix, XNU is referred to as macOS's "kernel" and the heart of what makes macOS tick **Kexts** | Also known as **K**ernel **Ext**ensions, are macOS's drivers. They're used to perform different tasks like device drivers or for a different purpose (in this patcher) like patching the OS, injecting information or running tasks. **KernelCollection** | Also known as the ImmutableKernel and PrelinkedKernel, this is a bundle of the kernel(XNU) and kernel extensions(Kexts) that we use to boot macOS. This is also what OpenCore patches in memory to allow us to have a seamless experience
- PrelinkedKernel: Default caching system since 10.7
- ImmutableKernel: Secure Boot based caching system since 10.13
- KernelCollection: Merge of both Prelinked and ImmutableKernel's since macOS 11, Big Sur **IOKit** | Backbone of how Kernel Extensions (Kexts) probe and attach onto hardware, starts quickly after kernel initiates **WindowServer** | Backbone of the GUI interface in macOS, one of the first userfacing userspace programs to kick-in **OTA** | Short for **O**ver **T**he **A**ir, refers to native OS updates via System Preferences like a supported Mac **DELTA** | Often used with OTA, refers to OS updates that much smaller than full installers (generally ~3GB), note Deltas require the root volume to be unmodified otherwise ~12GB updates will occur. --- Term | Description --- | --- **EFI** | It can denote two things:
- Mac's firmware, which is the same as UEFI, but pretty modified for Macs only, so not so "Universal"
- The partition on your hard drive that stores software read by the UEFI to load OSes (like the Windows bootloader) or UEFI Applications (like OpenCore), it's FAT32 formatted and has an ID type of EF00 (in hex). It can be named ESP or SYSTEM, and it's usually from 100MB to 400MB in size but the size doesn't reflect upon anything. **HFS+** | Also known as Mac OS Extended (Journaled), this was the default macOS drive format up until macOS 10.13. It was designed around spinning disks. **APFS** | This is the default macOS drive format from macOS 10.13 and onwards for SSDs, and standard for all drives in Mojave. This format was designed primarily around SSDs. **32 and 64-Bit CPU** | The bit number of a CPU determines how much data a CPU can address.
- 32-Bit CPUs were only supported up-to Mac OS X 10.6, Snow Leopard. **32-Bit Firmware** | The bit number of a Firmware determines how much data the firmware can address. In some older Macs, it's common to have a 64-Bit CPU with a 32-Bit firmware
- 32-Bit Firmwares were only supported up-to Mac OS X 10.7, Lion. **SSE Instructions** | Also known as **S**IMD **S**ingle-Precision Floating-Point **I**nstructions, these are defined as instruction sets supported by your CPU. In macOS, there are a certain number of instruction sets required for normal operation:
- SSE3: Required for all Intel CPUs since Mac OS X 10.4, Tiger
- SSSE3: Required for all Intel 64-Bit CPUs since Mac OS X 10.6, Snow Leopard
- SSE4.1: Required for all Intel CPUs since macOS 10.12, Sierra --- --- ### TIMEMACHINE (`docs/TIMEMACHINE.md`) # Restoring Time Machine backup OCLP automatically installs root patches when installing from the USB drive for the first time to ensure smooth operation of the first time settings. However, as an unfortunate side effect, doing a full restore via Time Machine breaks while root patches are installed and restoring requires a few tricks to avoid a kernel panic. Below are two different methods to restore. **Method 2 is only supported on Monterey and newer. Big Sur does not support snapshot reversion.** ::: warning Warning for Sequoia Time Machine on Sequoia may not function even after uninstalling root patches, leading to a loop with "Migration Finished" window. If you encounter this issue, restore on older OS and then upgrade to Sequoia. ::: ## Method 1 - Restore with root patches installed (partial) **Warning:** Be advised that with this method, folders **other than** "Desktop", "Documents", "Applications" etc (main folders under profile) may not be restored. If you want a full restore, use method 2 below. 1. Start Time Machine restore either in Setup Assistant (first time settings) or Migration Assistant. 2. When asked to select information to transfer, **uncheck** "Other files and folders" as seen in the image below. 3. Start transfer.
Uncheck other files and folders
Now you should be restored with your user profile, applications and settings. ## Method 2 - Restore without root patches (full) 1. In first time settings (Setup Assistant), do not restore the backup. Instead do all settings like you would want to start fresh. 2. Once you reach desktop, open the OCLP application and revert root patches in the Post Install Volume Patches section. 3. Restart your machine. * Note: Your Mac will feel slow due to lack of graphics drivers and resolution may be wrong. WiFi will also be unavailable in most cases, if your backup is on a network drive, use Ethernet. 4. Login and start Migration Assistant. 5. Go through the restoring process. 6. Once finished, go into the OCLP app and reinstall the root patches. Now you should be fully restored with Time Machine and also running with all patches. --- ### TROUBLESHOOT APP (`docs/TROUBLESHOOT-APP.md`) # Application issues * [OpenCore Legacy Patcher not launching](#opencore-legacy-patcher-not-launching) * [Privileged Helper Tool not found](#privileged-helper-tool-not-found) * ["You don't have permission to save..." error when creating USB installer](#you-don-t-have-permission-to-save-error-when-creating-usb-installer) * [Internal disk missing when building OpenCore](#internal-disk-missing-when-building-opencore) * ["Unable to resolve dependencies, error code 71" when root patching](#unable-to-resolve-dependencies-error-code-71-when-root-patching) * [System version mismatch error when root patching](#system-version-mismatch-error-when-root-patching) ## OpenCore Legacy Patcher not launching If the application won't launch (e.g. icon will bounce in the Dock), try launching OCLP via Terminal by typing the following command. ```sh /Library/Application Support/Dortania/OpenCore-Patcher.app/Contents/MacOS/OpenCore-Patcher ``` ## Privileged Helper Tool not found OCLP needs a Privileged Helper Tool to run parts of the application as root. If you encounter this error, reinstall OCLP using the PKG installer to fix Privileged Helper Tool. If your system lacks WiFi connection due to lack of patches, use Ethernet. You can also use another computer to download the app and move it to a USB drive. * In OCLP 2.3.0 and newer, using PKG is the only way to install and app.zip method has been discontinued. ## "You don't have permission to save..." error when creating USB installer In some cases, a following error saying "The bless of the installer disk failed" stating the reason as "You don't have permission to save..." may appear.
NoPermissionToSave
To resolve this, you may try adding Full Disk Access permission for OpenCore Legacy Patcher. To add it, first go to the settings * Ventura and Sonoma: Go to System Settings -> Privacy and Security -> Full Disk Access * Big Sur and Monterey: Go to System Preferences -> Security and Privacy -> Full Disk Access Enable OpenCore-Patcher in the list. If not found on the list, press the + sign to add a new entity and find OpenCore Legacy Patcher from Applications. Restart OpenCore Legacy Patcher and try creating your USB drive again. Optional: After you've created your USB drive, you can remove OpenCore Legacy Patcher from Full Disk Access again. ## Internal disk missing when building OpenCore If you're using a brand new disk that has not been used before or was never formatted in any macOS type, you may face the following error in OCLP when trying to build on the internal disk.
Failed to find applicable disks
There are two ways to to try and resolve this. 1. Create a new FAT32 partition using Disk Utility, sized at around 100MB, naming does not matter. OpenCore will detect it and you will be able to build your EFI there. 2. When installing macOS, choose "View -> Show all devices" in Disk Utility and format the entire disk by choosing the topmost option in the sidebar.
Wipe disk
## "Unable to resolve dependencies, error code 71" when root patching If you're getting this error, it typically means you have some offending kernel extensions, to fix this you will have to clear them. Semi-automated way: 1. Open Terminal 2. Type `sudo zsh` 3. Type `cd "/Volumes/Macintosh HD/Library/Extensions" && ls | grep -v "HighPoint*\|SoftRAID*" | xargs rm -rf` * Make sure to rename "Macintosh HD" to what your drive name is 4. Run OCLP root patcher again Manual way: 1. Navigate to /Library/Extensions 2. Delete everything **except** HighPointIOP.kext, HighPointRR.kext and SoftRAID.kext 3. Run OCLP root patcher again If there is no success, navigate to "/Library/Developer/KDKs" and delete everything. If still no success, type `sudo bless --mount "/Volumes/Macintosh HD/" --bootefi --last-sealed-snapshot` * Make sure again to rename "Macintosh HD" to what your drive name is Run OCLP root patcher again. ## System version mismatch error when root patching Due to a change by Apple, updates now modify the system volume **already while downloading**, which can lead to broken patches out of a sudden, since the operating system gets into a liminal state between two versions. Hence while root patching, you may get an error that looks like the following: `SystemVersion.plist build version mismatch: found 15.4 (24E247), expected 13.7.5 (22H527)` In this example, it is telling that a version 13.7.5 (Ventura) is expected which is currently running but macOS has already staged an update to version 15.4 (Sequoia) and has already modified the filesystem to prepare for an update, including writing the new version in SystemVersion.plist where OCLP is able to read it from. The "version mismatch" error is a safeguard preventing OCLP from patching on a system that is in a weird liminal state, to avoid leading to a very likely boot failure. There are few options to resolve it: 1. Update/upgrade to the version already staged. * This option works only if the newer version is currently supported by OCLP. 2. Reinstall macOS. * You can try doing an in-place install without wiping the disk to keep your data but this may not be possible due to the OS being partially on newer version and it will complain about downgrade. 3. Use an experimental "PurgePendingUpdate" tool [from the Discord server](https://discord.gg/rqdPgH8xSN). * Navigate to `support-forum` and then to the `Information and known issues` post to find the link to the tool. * Download it and then run it in Terminal to get rid of a pending update, then repatch again. If "purge failed" appears, you can ignore it. * Sometimes you may have to give the file an execution permission with `chmod +x` and putting the application path after the command (type or drag the file) before the tool can be ran. * This may be integrated into OCLP later on, however there is currently no ETA. **Disabling automatic macOS updates is extremely recommended once recovered, to prevent it from happening again.** * Note: macOS Sequoia has begun prompting to enable automatic updates from 15.4 onward after an update install has finished and isn't giving a choice to fully decline, this means you may have to keep doing it again after updating to newer versions. ::: details How to disable updates (click to expand) **macOS Ventura and newer:** System Settings -> General -> Software Update -> (i) button next to Automatic Updates -> Disable "Download new updates when available". **macOS Big Sur and Monterey:** System Preferences -> Software Update -> Advanced -> Disable "Download new updates when available". ::: --- ### TROUBLESHOOT HARDWARE (`docs/TROUBLESHOOT-HARDWARE.md`) # Hardware issues #### General * [No Brightness Control](#no-brightness-control) * [Cannot connect Wi-Fi on Monterey with legacy cards](#cannot-connect-wi-fi-on-monterey-with-legacy-cards) * [No Graphics Acceleration](#no-graphics-acceleration) * [No DisplayPort Output on Mac Pros with NVIDIA Kepler](#no-displayport-output-on-mac-pros-with-nvidia-kepler) * [Secondary CPU not visible on MacPro3,1/Xserve2,1](#secondary-cpu-not-visible-on-macpro3-1-xserve2-1) * [No acceleration after a Metal GPU swap on Mac Pro](#no-acceleration-after-a-metal-gpu-swap-on-mac-pro) * [Keyboard, Mouse and Trackpad not working in installer or after update](#keyboard-mouse-and-trackpad-not-working-in-installer-or-after-update) * [No T1 functionality after installing Sonoma or newer](#no-t1-functionality-after-installing-sonoma-or-newer) #### Non-Metal * [Keyboard Backlight broken](#keyboard-backlight-broken) * [Wake from sleep heavily distorted on AMD/ATI from macOS 11.3 to Monterey](#wake-from-sleep-heavily-distorted-on-ati-amd-terascale-1-from-macos-11-3-to-monterey) * [Unable to switch GPUs on 2011 15" and 17" MacBook Pros](#unable-to-switch-gpus-on-2011-15-and-17-macbook-pros) * [Erratic Colours on ATI TeraScale 2 GPUs (HD5000/HD6000)](#erratic-colours-on-ati-terascale-2-gpus-hd5000-hd6000) * [Cannot Login on 2011 15" and 17" MacBook Pros](#cannot-login-on-2011-15-and-17-macbook-pros) * [Black Boxes on HD3000 iGPUs](#black-boxes-on-hd3000-igpus) * [Cannot Pair Bluetooth Devices](#cannot-pair-bluetooth-devices) For those unfamiliar with what is considered a non-Metal GPU, see the chart in [FAQ](https://dortania.github.io/OpenCore-Legacy-Patcher/FAQ.html#what-is-metal-and-non-metal) ## No Brightness Control With OCLP v0.0.22, we've added support for brightness control on many models. However, some users may have noticed that their brightness keys do not work. As a work-around, we recommend users try out the below app: * [Brightness Slider](https://actproductions.net/free-apps/brightness-slider/) ## Cannot connect Wi-Fi on Monterey with legacy cards With OCLP v0.2.5, we've added support for legacy Wi-Fi on Monterey. However, some users may have noticed that they can't connect to wireless networks. To work-around this, we recommend that users manually connect using the "Other" option in the Wi-Fi menu bar or manually adding the network in the "Network" preference pane. ## No Graphics Acceleration In macOS, GPU drivers are often dropped from the OS with each major release of it. If you're using OCLP v0.4.4 or newer, you should have been prompted to install Root Volume patches after the first boot from installation of macOS. If you need to do this manually, you can do so within the patcher app. Once rebooted, acceleration will be re-enabled as well as brightness control for laptops. See [Applying Post Install Volume Patches](https://dortania.github.io/OpenCore-Legacy-Patcher/POST-INSTALL.html#applying-post-install-volume-patches) for more information. If you swapped a GPU from stock to a Metal GPU in a Mac Pro after installing OS, see [No acceleration after a Metal GPU swap on Mac Pro](#no-acceleration-after-a-metal-gpu-swap-on-mac-pro) for instructions. Check the list below to see what GPUs require patching in which OS versions. :::details GPUs requiring patching in different macOS versions AMD Navi (RX 5000 - 6000 series) GPUs are non-functional in Mac Pro 2008 to 2012 using Ventura and newer due to lack of AVX2 support. **Sequoia** * NVIDIA: * Tesla (8000 - 300 series) * Kepler (600 - 800 series) * AMD: * TeraScale (2000 - 6000 series) * GCN 1-3 (7000 - R9 series) * Polaris (RX 4xx/5xx series, if CPU lacks AVX2) * Intel: * Iron Lake * Sandy Bridge (2000 - 3000 series) * Ivy Bridge (4000 series) * Haswell (4400, 4600, 5000 series) * Broadwell (6000 series) * Skylake (500 series) **Sonoma** * NVIDIA: * Tesla (8000 - 300 series) * Kepler (600 - 800 series) * AMD: * TeraScale (2000 - 6000 series) * GCN 1-3 (7000 - R9 series) * Polaris (RX 4xx/5xx series, if CPU lacks AVX2) * Intel: * Iron Lake * Sandy Bridge (2000 - 3000 series) * Ivy Bridge (4000 series) * Haswell (4400, 4600, 5000 series) * Broadwell (6000 series) * Skylake (500 series) **Ventura** * NVIDIA: * Tesla (8000 - 300 series) * Kepler (600 - 800 series) * AMD: * TeraScale (2000 - 6000 series) * GCN 1-3 (7000 - R9 series) * Polaris (RX 4xx/5xx series, if CPU lacks AVX2) * Intel: * Iron Lake * Sandy Bridge (2000 - 3000 series) * Ivy Bridge (4000 series) * Haswell (4400, 4600, 5000 series) * Broadwell (6000 series) * Skylake (500 series) **Monterey** * NVIDIA: * Tesla (8000 - 300 series) * Kepler (600 - 800 series) * AMD: * TeraScale (2000 - 6000 series) * Intel: * Iron Lake * Sandy Bridge (2000 - 3000 series) * Ivy Bridge (4000 series) **Big Sur** * NVIDIA: * Tesla (8000 - 300 series) * AMD: * TeraScale (2000 - 6000 series) * Intel: * Iron Lake * Sandy Bridge (2000 - 3000 series) ::: ## No DisplayPort Output on Mac Pros with NVIDIA Kepler If you're having trouble with DisplayPort output on Mac Pros, try enabling Minimal Spoofing in Settings -> SMBIOS Settings and rebuild/install OpenCore. This will trick macOS drivers into thinking you have a newer MacPro7,1 and resolve the issue.
GUI SMBIOS minimal
## Intermediate issues with USB 1.1 and Bluetooth on MacPro3,1 - MacPro5,1 For those experiencing issues with USB 1.1 devices (such as mice, keyboards and bluetooth chipsets), macOS Big Sur and newer have weakened OS-side reliability for the UHCI controller in older Mac Pros. * UHCI is a USB 1.1 controller that is hooked together with the USB 2.0 ports in your system. Whenever a USB 1.1 device is detected, the UHCI controller is given ownership of the device at a hardware/firmware level. * EHCI is the USB 2.0 controller in older Mac Pros Because of this, we recommend placing a USB 2.0/3.0 hub between your devices and the port on the Mac Pro. UHCI and EHCI cannot both be used at once, so using a USB hub will always force the EHCI controller on. * Alternatively, you can try cold-starting the hardware and see if macOS recognizes the UHCI controller properly. ## Secondary CPU not visible on MacPro3,1/Xserve2,1 Starting with macOS Sequoia, OCLP has to disable the secondary CPU in these systems to avoid a panic. This also means by default, only single CPU will be usable even on older versions. To re-enable both CPUs on older versions, do the following: 1. Open Settings -> `Build` tab. 2. Untick `MacPro3,1/Xserve2,1 Workaround`. 3. Rebuild OpenCore. 4. Reboot. **Dual CPUs cannot be enabled in any circumstance if Sequoia or newer is installed, even in multiboot scenarios. Doing so will make Sequoia unbootable.** [More information here](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1136#:~:text=we%20cannot%20verify.-,MacPro3%2C1%20Dual%20Socket%20Support,-Currently%20on%20macOS) ## No acceleration after a Metal GPU swap on Mac Pro If you finished installing macOS with the original card installed (to see bootpicker for example) and swapped your GPU to a Metal supported one, you may notice that you're missing acceleration. To fix this, open OCLP and revert root patches to get your Metal-supported GPU work again. In macOS Ventura and newer, repatching is needed for most configurations after reversion. Reason why this happens is automatic root patching during USB install and the autopatcher assuming you will be using the original graphics card and therefore doing non-Metal patching. **Metal and non-Metal GPUs cannot be used at the same time** as Non-Metal patching completely bypasses Metal and requires removing some parts such as drivers for other cards, which causes Metal cards to not accelerate after swapping. Alternatively, you can remove "AutoPkg-Assets.pkg" from /Library/Packages on the USB drive before proceeding with the installation. This package includes the assets for root patching and the system won't be autopatched if they aren't present. To see the folder, enable hidden files with `Command` + `Shift` + `.` ## Keyboard, Mouse and Trackpad not working in installer or after update Starting from macOS Ventura, USB 1.1 drivers are no longer provided in the operating system. For Macs using legacy USB 1.1 controllers, OpenCore Legacy Patcher can only restore support once it has performed root volume patches which restore the drivers. Thus when installing macOS or after an update, you need to hook up a USB hub between your Mac and keyboard/mouse, forcing USB 2.0 mode in order to install the root patches. * For MacBook users, you'll need to find an external keyboard/mouse in addition to the USB hub Applicable models include: | Family | Year | Model | Notes | | :---------- | :--------------------| :---------------------------- | :----------------------------------------------- | | MacBook | Mid 2010 and older | MacBook5,1 - MacBook7,1 | | | MacBook Air | Late 2010 and older | MacBookAir2,1 - MacBookAir3,x | | | MacBook Pro | Mid 2010 and older | MacBookPro4,1 - MacBookPro7,x | Excludes Mid 2010 15" and 17" (MacBookPro6,x) | | iMac | Late 2009 and older | iMac7,1 - iMac10,x | Excludes Core i5/7 27" late 2009 iMac (iMac11,1) | | Mac mini | Mid 2011 and older | Macmini3,1 - Macmini5,x | | | Mac Pro | Mid 2010 and older | MacPro3,1 - MacPro5,1 | |
USB1.1 chart
::: warning Note In macOS Sonoma, this seems to have been further weakened and some hubs may not be functional. If you encounter this issue, try another hub. ::: ### Alternative method for Software Update Alternative way for updates is making sure to enable "Remote Login" in General -> Sharing before updating, which will enable SSH. That means you can take control using Terminal in another system and run Post Install Volume Patching. **This only applies to updates via Software Update and is not applicable when booting to installer via USB drive.** Use the following commands: 1. `ssh username@lan-ip-address` - Connects via SSH, change username and IP address to the system's 2. `/Applications/OpenCore-Patcher.app/Contents/MacOS/OpenCore-Patcher --patch_sys_vol` - Installs root patches via CLI 3. `sudo reboot`. More information can be found here: * [Legacy UHCI/OHCI support in Ventura #1021](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1021) ## No T1 functionality after installing Sonoma or newer If you notice your Touchbar etc not working, this means loss of T1 functionality. Wiping the entire disk using Disk Utility with Sonoma or newer causes the T1 firmware to be removed, which due to removed support, the macOS Sonoma+ installer will not restore. If the firmware is missing from EFI, T1 will not work regardless whether OCLP reinstates the driver during root patching. To restore T1 functionality, Ventura or older has to be reinstalled. This can be done in another volume or external disk as well, as long as the OS is booted once. After this you can wipe the old OS or unplug the external disk. To prevent this from happening in the future, with T1 systems only wipe the volume containing the operating system.
WipeVolume
## Keyboard Backlight broken Due to forcing `hidd` into spinning up with the fallback mode enabled, this can break the OS's recognition of backlight keyboards. Thankfully the drivers themselves still do operate so applications such as [LabTick](https://www.macupdate.com/app/mac/22151/lab-tick) are able to set the brightness manually. ::: details For Big Sur (click to expand) Due to the Metal Backend, the enhanced color output of these apps seems to heavily break overall UI usage. To work around this, [users reported](https://forums.macrumors.com/threads/macos-11-big-sur-on-unsupported-macs-thread.2242172/post-29870324) forcing the color output of their monitor from Billions to Millions of colors helped greatly. Apps easily allowing this customization are [SwitchResX](https://www.madrau.com), [ResXreme](https://macdownload.informer.com/resxtreme/) and [EasyRes](http://easyresapp.com). ::: ## Wake from sleep heavily distorted on ATI/AMD TeraScale 1 from macOS 11.3 to Monterey **Fixed for macOS Ventura starting from 0.6.6. Big Sur and Monterey will continue to exhibit the issue.** This issue affects TeraScale 1 GPUs (ie. ATI/AMD Radeon HD2000-4000). Only known solution is to downgrade to macOS 11.2.3 or older. Additionally, logging out and logging back in can resolve the issue without requiring a reboot. In the event Apple removes 11.2.3 from their catalogue, we've provided a mirror below: * [Install macOS 11.2.3 20D91](https://archive.org/details/install-mac-os-11.2.3-20-d-91) ## Unable to switch GPUs on 2011 15" and 17" MacBook Pros Currently, with OpenCore Legacy Patcher, GPU switching between the iGPU and dGPU is broken. The simplest way to set a specific GPU is to disable the dGPU when you wish to remain on the more power efficient iGPU. The best way to achieve this is to boot to Recovery (or Single User Mode if the dGPU refuses to function at all) and run the following command: ```sh nvram FA4CE28D-B62F-4C99-9CC3-6815686E30F9:gpu-power-prefs=%01%00%00%00 ``` This will disable the dGPU and allow the iGPU to function in Big Sur. Note that external display outputs are directly routed to the dGPU and therefore can no longer be used. Solutions such as [DisplayLink Adapters](https://www.displaylink.com/products/usb-adapters) can work around this limitation, however, note that you'll need to use older drivers (5.2.6): * [DisplayLink USB Graphics Software for macOS - For Mojave and Catalina - 5.2.6](https://www.synaptics.com/products/displaylink-graphics/downloads/macos-5.2.6) Note: This driver only provides partial support in macOS, full graphics acceleration is not currently available on displays driven by DisplayLink. ## Erratic Colours on ATI TeraScale 2 GPUs (HD5000/HD6000) Resolved with OpenCore Legacy Patcher v0.4.2 ::: details Legacy Fix (prior to 0.4.2) Due to an odd bug with ATI's TeraScale 2 GPUs, many users will experience erratic/strobing colours once finished installing accelerated patches and rebooting into macOS. The issue stems from an incorrect assumption in the GPU drivers where it will enforce the Billion Colour space on your display. To fix, simply force your Display into a lower color depth such as Million Colours. Applications that can set color depth are: * [SwitchResX](https://www.madrau.com) * [ResXtreme](https://macdownload.informer.com/resxtreme/) ::: ## Cannot Login on 2011 15" and 17" MacBook Pros By default, OpenCore Legacy Patcher will assume MacBookPro8,2/3 have a faulty dGPU and disable acceleration. This is the safest option for most users as enabling dGPU acceleration on faulty Macs will result in failed booting. However, if your machine does not have the dGPU disabled via NVRAM, you'll experience a login loop. To work around this is quite simple: 1. Boot macOS in Single User Mode * Press Cmd+S in OpenCore's menu when you turn the Mac on 2. When the command line prompt appears, enter the dGPU disabler argument (at the bottom) 3. Reboot and patched macOS should work normally 4. If you still want to use the dGPU, run OpenCore Legacy Patcher and enable TS2 Acceleration from settings. Go to `Settings -> Root Patching -> TeraScale 2 Acceleration`, then root patch again. 5. Either Reset NVRAM or set `gpu-power-prefs` to zeros to re-enable the dGPU ```sh # Forces GMUX to use iGPU only (ie. disable dGPU) nvram FA4CE28D-B62F-4C99-9CC3-6815686E30F9:gpu-power-prefs=%01%00%00%00 # To reset, simply write zeros or NVRAM Reset your Mac nvram FA4CE28D-B62F-4C99-9CC3-6815686E30F9:gpu-power-prefs=%00%00%00%00 ``` ## Black Boxes on HD3000 iGPUs A somewhat strange issue on Intel HD3000-based Macs, on 3rd party displays sometimes UI elements may become black and unreadable. To resolve, select either the generic `Display` or `Display P3` Color Profiles in Display Settings. * Mainly applicable for HDMI Displays, DVI and DisplayPort are generally unaffected. * If you're inside Setup Assistant, press `Cmd` + `Option` + `Control` + `T` to launch Terminal. From there, run `open /System/Applications/System\ Preferences.app` * Issue has spread to more Macs with macOS Ventura, including MacBook Airs and MacBook Pros | Default Color Profile | Display/Display P3 Profile | | :--- | :--- | | | | ## Cannot Pair Bluetooth Devices In macOS Ventura, hover states may not function correctly which results in the "Connect" button not appearing in System Settings. To resolve: 1. Enable Keyboard Navigation in System Settings -> Keyboard 2. Tab + space over Bluetooth devices in System Settings -> Bluetooth 3. Pair button should appear For more information, see [ASentientBot's post](https://forums.macrumors.com/threads/macos-13-ventura-on-unsupported-macs-thread.2346881/page-116?post=31858759#post-31858759). --- ### TROUBLESHOOT MISC (`docs/TROUBLESHOOT-MISC.md`) # Booting, installer and other issues #### Booting * [Stuck on `This version of Mac OS X is not supported on this platform` or (🚫) Prohibited Symbol](#stuck-on-this-version-of-mac-os-x-is-not-supported-on-this-platform-or-🚫-prohibited-symbol) * [Cannot boot macOS without the USB](#cannot-boot-macos-without-the-usb) * [Infinite Recovery OS Booting](#infinite-recovery-os-booting) * [Stuck on boot after root patching](#stuck-on-boot-after-root-patching) * [Booting Recovery through OpenCore Legacy Patcher](#booting-recovery-through-opencore-legacy-patcher) * [Black Screen on MacBookPro11,3 in macOS Monterey](#black-screen-on-macbookpro11-3-in-macos-monterey) #### Installer * [Stuck on hard disk selection with greyed out buttons in installer](#stuck-on-hard-disk-selection-with-greyed-out-buttons-in-installer) * [Installer fails with "an error occurred preparing the software update"](#installer-fails-with-an-error-occurred-preparing-the-software-update) * [Stuck on "Less than a minute remaining..."](#stuck-on-less-than-a-minute-remaining) * [Stuck on "Your Mac needs a firmware update"](#stuck-on-your-mac-needs-a-firmware-update) #### Other * [Reboot when entering Hibernation (`Sleep Wake Failure`)](#reboot-when-entering-hibernation-sleep-wake-failure) * [Volume Hash Mismatch Error in macOS Monterey](#volume-hash-mismatch-error-in-macos-monterey) * [Cannot Disable SIP in recoveryOS](#cannot-disable-sip-in-recoveryos) ## Stuck on `This version of Mac OS X is not supported on this platform` or (🚫) Prohibited Symbol This means macOS has detected an SMBIOS it does not support. To resolve this, ensure you're booting OpenCore **before** the macOS installer in the boot picker. Reminder that the option will be called `EFI Boot`. Once you've booted OpenCore at least once, your hardware should now auto-boot it until either an NVRAM reset occurs, or you remove the drive with OpenCore installed. However, if the 🚫 Symbol only appears after the boot process has already started (the bootscreen appears/verbose boot starts), it could mean that your USB drive has failed to pass macOS' integrity checks. To resolve this, create a new installer using a different USB drive (preferably of a different model.) ## Cannot boot macOS without the USB By default, the OpenCore Patcher won't install OpenCore onto the internal drive itself during installs. After installing macOS, OpenCore Legacy Patcher should automatically prompt you to install OpenCore onto the internal drive. However, if it doesn't show the prompt, you'll need to either [manually transfer](https://dortania.github.io/OpenCore-Post-Install/universal/oc2hdd.html) OpenCore to the internal drive's EFI or Build and Install again and select your internal drive. Reminder that once this is done, you'll need to select OpenCore in the boot picker again for your hardware to remember this entry and auto boot from then on. ## Infinite Recovery OS Booting With OpenCore Legacy Patcher, we rely on Apple Secure Boot to ensure OS updates work correctly and reliably with Big Sur. However this installs NVRAM variables that will confuse your Mac if not running with OpenCore. To resolve this, simply uninstall OpenCore and [reset NVRAM](https://support.apple.com/en-mide/HT201255). * Note: Machines with modified root volumes will also result in an infinite recovery loop until integrity is restored. ## Stuck on boot after root patching **Applies to macOS Monterey and newer. Big Sur does not support snapshot reversion.** Boot into recovery by pressing space when your disk is selected on the OCLP bootpicker (if you have it hidden, hold ESC while starting up) * **Note:** If your disk name is something else than "Macintosh HD", make sure to change the path accordingly. You can figure out your disk name by typing `ls /Volumes`. Go into terminal and first mount the disk by typing ```sh mount -uw "/Volumes/Macintosh HD" ``` Then revert the snapshot ```sh bless --mount "/Volumes/Macintosh HD" --bootefi --last-sealed-snapshot ``` Now we're going to clean the /Library/Extensions folder from offending kexts while keeping needed ones. Run the following and **make sure to type it carefully** ::: warning If you have **FileVault 2 enabled**, you will need to mount the Data volume first. This can be done in Disk Utility by locating your macOS volume name, selecting its Data volume, and selecting the Mount option in the toolbar. ::: ```sh cd "/Volumes/Macintosh HD - Data/Library/Extensions" && ls | grep -v "HighPoint*\|SoftRAID*" | xargs rm -rf ``` Then restart and now your system should be restored to the unpatched snapshot and should be able to boot again. ## Booting Recovery through OpenCore Legacy Patcher Booting into Recovery through the regular key combination (cmd+r) will result in a "no entry" screen, due to the checks detecting an unsupported Mac. To access Recovery, you will have to boot it through OpenCore using the bootpicker. By default, the patcher will try to hide extra boot options such as recovery from the user. To make them appear, press the `Spacebar` key while inside OpenCore's bootpicker to list all boot options and select recovery for the corresponding OS version. ## Black Screen on MacBookPro11,3 in macOS Monterey Due to Apple dropping NVIDIA Kepler support in macOS Monterey, [MacBookPro11,3's GMUX has difficulties switching back to the iGPU to display macOS correctly.](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/522) To work-around this issue, boot the MacBookPro11,3 in Safe Mode and once macOS is installed, run OCLP's Post Install Root Patches to enable GPU Acceleration for the NVIDIA dGPU. * Safe Mode can be started by holding `Shift` + `Enter` when selecting macOS Monterey in OCLP's Boot Menu. ## Stuck on hard disk selection with greyed out buttons in installer Switch installer language to English. If the language selector doesn't show up, [reset NVRAM](https://support.apple.com/en-mide/102603) and boot into the installer again. You can switch back to different language once macOS has installed. ## Installer fails with "an error occurred preparing the software update" This issue can be faced in the second phase of the installer with black background and Apple logo, cause of this issue is unknown. To possibly resolve this issue, keep rebooting into 'macOS Installer' (the second phase) multiple times until it ultimately goes through. ## Stuck on "Less than a minute remaining..." A common area for systems to get "stuck", namely for units that are missing the `AES` CPU instruction/older mobile hardware. During this stage, a lot of heavy cryptography is performed, which can make systems appear to be stuck. In reality they are working quite hard to finish up the installation. Because this step can take a few hours or more depending on drive speeds, be patient at this stage and do not manually power off or reboot your machine as this will break the installation and require you to reinstall. If you think your system has stalled, press the Caps Lock key. If the light turns on, your system is busy and not actually frozen. ## Stuck on "Your Mac needs a firmware update" Full error: "Your Mac needs a firmware update in order to install to this Volume. Please select a Mac OS Extended (Journaled) volume instead." This error occurs when macOS determines that the current firmware does not have full APFS support. To resolve this, when installing OpenCore, head to "Patcher Settings" and enable "Moderate SMBIOS Patching" or higher. This will ensure that the firmware reported will show support for full APFS capabilities. ## Reboot when entering Hibernation (`Sleep Wake Failure`) [Known issue on some models](https://github.com/dortania/Opencore-Legacy-Patcher/issues/72), a temporary fix is to disable Hibernation by executing the following command in the terminal: ``` sudo pmset -a hibernatemode 0 ``` ## Volume Hash Mismatch Error in macOS Monterey A semi-common popup some users face is the "Volume Hash Mismatch" error:

What this error signifies is that the OS detects that the boot volume's hash does not match what the OS is expecting, this error is generally cosmetic and can be ignored. However if your system starts to crash spontaneously shortly after, you'll want to reinstall macOS fresh without importing any data at first. * Note that this bug affects native Macs as well and is not due to issues with unsupported Macs: [OSX Daily: “Volume Hash Mismatch” Error in MacOS Monterey](https://osxdaily.com/2021/11/10/volume-hash-mismatch-error-in-macos-monterey/) Additionally, it can help to disable FeatureUnlock in Settings -> Misc Settings as this tool can be strenuous on systems with weaker memory stability. ## Cannot Disable SIP in recoveryOS With OCLP, the patcher will always overwrite the current SIP value on boot to ensure that users don't brick an installation after an NVRAM reset. However, for users wanting to disable SIP entirely, this can be done easily. Head into the GUI, go to Patcher Settings, and toggle the bits you need disabled from SIP: | SIP Enabled | SIP Lowered (Root Patching) | SIP Disabled | | :--- | :--- | :--- | | | | | --- ### TROUBLESHOOT NONMETAL (`docs/TROUBLESHOOT-NONMETAL.md`) # Non-Metal issues The below page is for users experiencing issues with their overall usage of macOS Big Sur and newer and the Legacy Graphics Acceleration patches. For those unfamiliar with what is considered a non-Metal GPU, see the chart in [FAQ](https://dortania.github.io/OpenCore-Legacy-Patcher/FAQ.html#what-is-metal-and-non-metal) * [Broken Firefox and Thunderbird (HD 3000)](#broken-firefox-and-thunderbird-hd-3000) * [Broken Background Blurs](#broken-background-blurs) * [Downloading older non-Metal Apps](#downloading-older-non-metal-apps) * [Unable to run Zoom](#unable-to-run-zoom) * [Unable to grant special permissions to apps (ie. Camera Access to Zoom)](#unable-to-grant-special-permissions-to-apps-ie-camera-access-to-zoom) * [Photos and Maps app issues](#photos-and-maps-app-issues) * [Cannot press "Done" when editing a Sidebar Widget](#cannot-press-done-when-editing-a-sidebar-widget) * [Unable to allow Safari Extensions](#unable-to-allow-safari-extensions) ## Broken Firefox and Thunderbird (HD 3000) Firefox and Thunderbird are now broken on HD 3000 [due to removal of HD 3000 support by Mozilla in v145.](https://hg-edge.mozilla.org/releases/mozilla-release/rev/32d4368e5a2a869bdc1f4556f020c1a6bea2a9c0) This may lead to system freezes and other erratic behavior on systems with this GPU, which is found in Mac models from 2011. As a workaround, hardware acceleration has to be disabled. If your system is locking up in normal mode, boot into Safe Mode by holding `Shift` on boot and disable hardware acceleration for Firefox and Thunderbird wherever applicable. ::: details Affected Mac models (click to expand) * MacBook Pro 2011 13", 15" and 17" * MacBook Air 2011 11" and 13" * Mac mini 2011 models without Radeon dGPU ::: ## Broken Background Blurs By default with the non-Metal acceleration patches, many background blur menus may act distorted when moving a cursor over it. With 0.4.1 and newer, users can enable a new Beta Blur feature to try and resolve the issue:
Beta Blur settings
Do note that enabling beta blurs can be more demanding on slower hardware ## Downloading older non-Metal Apps Many Apple apps now have direct reliance on Metal for proper functioning, however legacy builds of these apps still do work in Big Sur. See below for archive of many apps such as Pages, iMovie, GarageBand. * [Apple Apps for Non-Metal Macs](https://archive.org/details/apple-apps-for-non-metal-macs) Note: This archive assumes that you own these copies of these apps through the Mac App Store, Dortania does not condone piracy ## Unable to run Zoom Currently Zoom relies partially on Metal and so needs a small binary patch. Dosdude1 has provided a nice script for this: * [Zoom Non-Metal Fix](http://dosdude1.com/catalina/zoomnonmetal-new.command.zip) ## Unable to grant special permissions to apps (ie. Camera Access to Zoom) Currently for Ventura 13.3 and newer, due to new patches required, permissions are yet again broken. Use TCCPlus in the Workaround dropdown to work around the issue. This issue is fully resolved for 13.2.1 and lower starting from 0.2.5. ::: details Workaround for 0.2.4, Ventura 13.3+ Due to the usage of amfi_get_out_of_my_way=1, macOS will fail to prompt users for special permissions upon application start as well as omit the entries in System Preferences. To work around this, we recommend users install tccplus to manage permissions. [Download TCCPlus](https://github.com/jslegendre/tccplus) Example usage with Discord and microphone permissions: ```sh # Open Terminal and run the following commands cd ~/Downloads/ chmod +x tccplus ./tccplus add Microphone com.hnc.Discord ``` For those who may experience issues with `tccplus`, you can manually patch `com.apple.TCC` to add permissions: ```sh # get app id (Zoom.us used in example): $ osascript -e 'id of app "zoom.us"' # output: us.zoom.xos $ sudo sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db "INSERT or REPLACE INTO access VALUES('kTCCServiceMicrophone','us.zoom.xos',0,2,0,1,NULL,NULL,NULL,'UNUSED',NULL,0,1541440109);" $ sudo sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db "INSERT or REPLACE INTO access VALUES('kTCCServiceCamera','us.zoom.xos',0,2,0,1,NULL,NULL,NULL,'UNUSED',NULL,0,1541440109);" ``` ::: ## Photos and Maps app issues **Starting from macOS Monterey, Maps and everything relying on it (such as Find My or 'Places' in Photos) are non-functional on non-Metal due to Metal reliance.** ::: details For Big Sur (click to expand) Due to the Metal Backend, the enhanced color output of these apps seems to heavily break overall UI usage. To work around this, [users reported](https://forums.macrumors.com/threads/macos-11-big-sur-on-unsupported-macs-thread.2242172/post-29870324) forcing the color output of their monitor from Billions to Millions of colors helped greatly. Apps easily allowing this customization are [SwitchResX](https://www.madrau.com), [ResXreme](https://macdownload.informer.com/resxtreme/) and [EasyRes](http://easyresapp.com). ::: ## Cannot press "Done" when editing a Sidebar Widget Workaround: Press some combination of Tab, or Tab and then Shift-Tab, or just Shift-Tab until the "Done" button is highlighted. Then press spacebar to activate the button, the same as in any other dialog with a highlighted button halo. ## Unable to allow Safari Extensions Due to a bug in the legacy acceleration patches, users won't be able to enable Safari Extensions. The following tool can be used to work-around this issue: * [Non-Metal Safari Extensions](https://github.com/moosethegoose2213/Non-Metal-Safari-Extensions/) --- ### TROUBLESHOOTING (`docs/TROUBLESHOOTING.md`) This page has moved. - [Application troubleshooting](./TROUBLESHOOT-APP.md) - [Booting, installer and other troubleshooting](./TROUBLESHOOT-MISC.md) - [Non-Metal troubleshooting](./TROUBLESHOOT-NONMETAL.md) - [Hardware troubleshooting](./TROUBLESHOOT-HARDWARE.md) --- ### UNINSTALL (`docs/UNINSTALL.md`) # Uninstall This guide tells you different ways to uninstall OCLP and/or patches. ## Delete everything and revert back to native macOS 1. Create a USB drive with the latest officially supported macOS installer or alternatively [on most Macs](https://apple.stackexchange.com/questions/383985/which-macs-support-macos-internet-recovery) use Internet Recovery. * Hold `cmd` + `Option (Alt)` + `R` for Internet Recovery. * If doing Internet Recovery, skip step 2. * Caution: Internet Recovery may not always install the latest officially supported OS version. 3. Restart and boot the computer using the installer USB drive by holding `Option (Alt)`. 4. Go to Disk Utility and choose View -> Show All Devices. 5. Wipe the full disk by choosing the top disk option on the left sidebar and selecting "Erase". 6. Start macOS installation. 7. Once finished, restart once more and [Reset NVRAM](https://support.apple.com/HT204063) to ensure a fully clean and stock system. ## Manual methods Uninstalling OCLP manually is a three part process which includes the application, OpenCore and the root patches. If you want to remove OCLP and patches entirely, go through all three in succession. Otherwise do the part(s) you need. ### Reverting root patches Open the OCLP application and go into the Post Install Root Patch menu, choose Revert Root Patches. * **Supported on Monterey and later. Big Sur does not support snapshot reversion and requires a reinstall. Reinstall can be done without a wipe if the macOS installer version used is the same or newer.** ### Uninstalling the application To uninstall the OCLP application including LaunchAgent and PrivilegedHelperTool, download the uninstaller package from [the releases page.](https://github.com/dortania/OpenCore-Legacy-Patcher/releases) ### Uninstalling the bootloader 1. Remove OpenCore either from the USB or internal drive * Mount the drive's EFI partition, and delete the `EFI/OC` and `System` folders * Note: **Do not** delete the entire EFI folder, this will likely break any existing Windows and Linux installations. * [See here for an example on how to mount](https://dortania.github.io/OpenCore-Post-Install/universal/oc2hdd.html) * 5K iMac users, also delete `boot.efi` on the root of the EFI partition. 2. [Reset NVRAM](https://support.apple.com/HT204063) :::warning Note that after you remove OpenCore, your Mac will no longer boot and show the "prohibited" symbol. Be prepared to have a bootable USB drive with either OpenCore or natively-supported version of macOS before you uninstall the bootloader. * This does not apply to native Macs just using OpenCore to achieve features like AirPlay to Mac and Sidecar, but it is still recommended to reinstall macOS after removing OpenCore, if using SMBIOS spoofing to enable Universal Control and other features. ::: --- ### UNIVERSALCONTROL (`docs/UNIVERSALCONTROL.md`) # Universal Control on unsupported Macs Introduced in macOS 12 Monterey, Universal Control is a feature that allows a Mac to control other Macs and/or iPads, share input devices, and share files across them simultaneously. With OpenCore and FeatureUnlock, Universal Control can be unlocked for most unsupported Macs, as long as they meet the technical requirements listed on this page. ::: warning Note These features are not actively tested and may break at any time. The following page is primarily for tinkerers, no proper support is provided outside of Discord support (see bottom of page). ::: ## Enabling Universal Control If you meet all the requirements, in most cases you can go to Display Preferences and tick the Universal Control settings to enable it. If you're planning to use Universal Control with an iPad, make sure to enable Universal Control on the iPad as well. | Display Preferences | Universal Control settings | | :--- | :--- | | | | Most Mac models from 2011 and above should work out of the box. However, older Macs like the 2008-2011 MacBook Pros require upgrading the Wi-Fi/Bluetooth card to a newer model. More info in the [requirements section.](#requirements-for-universal-control) Some Monterey-native models are blacklisted, check the [blacklisted models section](#blacklisted-models) for more info. ## Requirements for Universal Control Technical requirements: * Wi-Fi 4 (802.11n) * Bluetooth 4.0 * macOS Monterey 12.4 or newer * iPadOS 15.4 or newer (if applicable) * OpenCore Legacy Patcher 0.4.3 or newer Check the [table of models](#table-of-models) below to see whether you need to upgrade hardware and exactly what hardware is required to be changed based on the offending Macs listed. For help on how to upgrade the Wi-Fi card in older 2008-2011 models, refer to the `#hardware` channel in the [Discord server](https://discord.gg/rqdPgH8xSN) if required. Other requirements: * All devices are signed into the same iCloud account. * Two Factor Authentication is enabled with your Apple ID. * Bluetooth and WiFi are enabled. Neither needs to be connected, leaving them enabled is sufficient. * Handoff turned on from iCloud settings. * The devices in question are in close proximity. ### Table of models This table shows which models do and do not support Universal Control out of box (OOB) and what is required to gain support. Note: For AirPort upgrades, only the best/newest cards are listed. ::: details MacBook | SMBIOS | WiFi/BT version | UC OOB | Comment | |------------|-----------------|------------|---------| | MacBook5,1 | Wi-Fi 4 / BT 2.0 EDR | NO | Use a Broadcom USB Bluetooth 4.0+ Dongle | | MacBook5,2 | WiFi 4 / BT 2.1 EDR | ^^ | Replace stock AirPort card with an mPCIE + USB Connector Adapter board with a BCM94360CS2 card | | MacBook6,1 | ^^ | ^^ | Replace stock AirPort card with a BCM94331PCIEBT4CAX/BCM94331PCIEBT4 card | | MacBook7,1 | ^^ | ^^ | ^^ | | MacBook8,1 | WiFi 4 + BT 4.2 | YES | Universal Control will work. | ::: ::: details MacBook Air | SMBIOS | WiFi/BT version | UC OOB | Comment | |--------|-----------------|------------|---------| | MacBookAir2,1 | Wi-Fi 4 / BT 2.1 EDR | NO | Use a Broadcom USB Bluetooth 4.0+ Dongle | | MacBookAir3,1 | ^^ | ^^ | Replace stock AirPort card with a BCM94360CS2 card | | MacBookAir3,2 | ^^ | ^^ | ^^ | | MacBookAir4,1 | Wi-Fi 4 + BT 4.0 | YES | Universal Control will work. | | MacBookAir4,2 | ^^ | ^^ | ^^ | | MacBookAir5,1 | ^^ | ^^ | ^^ | | MacBookAir5,2 | ^^ | ^^ | ^^ | | MacBookAir6,1 | Wi-Fi 5 + BT 4.0 | ^^ | ^^ | | MacBookAir6,2 | ^^ | ^^ | ^^ | | MacBookAir7,1 | ^^ | NO | Hardware supports UC.
[**Spoofing required.**](#blacklisted-models)| | MacBookAir7,2 | ^^ | ^^ | ^^ | ::: ::: details MacBook Pro | SMBIOS | WiFi/BT version | UC OOB | Comment | |--------|-----------------|-------------|---------| | MacBookPro4,1 | Wi-Fi 4 / BT 2.1 EDR | NO | Replace stock AirPort card with an mPCIE + USB Connector Adapter board with a BCM94360CS2 card | | MacBookPro5,1 | ^^ | ^^ | Use a Broadcom USB Bluetooth 4.0+ Dongle | | MacBookPro5,2 | ^^ | ^^ | ^^ | | MacBookPro5,3 | ^^ | ^^ | ^^ | | MacBookPro5,4 | ^^ | ^^ | ^^ | | MacBookPro5,5 | ^^ | ^^ | ^^ | | MacBookPro6,1 | ^^ | ^^ | ^^ | | MacBookPro6,2 | ^^ | ^^ | Replace stock AirPort card with a BCM94331PCIEBT4CAX/BCM94331PCIEBT4 card | | MacBookPro7,1 | ^^ | ^^ | Use a Broadcom USB Bluetooth 4.0+ Dongle | | MacBookPro8,1 | Wi-Fi 4 + BT 2.1 EDR | ^^ | Replace stock AirPort card with a BCM94331PCIEBT4CAX/BCM94331PCIEBT4 card | | MacBookPro8,2 | ^^ | ^^ | ^^ | | MacBookPro9,1 | Wi-Fi 4 + BT 4.0 | YES | Universal Control will work. | | MacBookPro9,2 | ^^ | ^^ | ^^ | | MacBookPro10,1 | ^^ | ^^ | ^^ | | MacBookPro10,2 | ^^ | ^^ | ^^ | | MacBookPro11,1 | Wi-Fi 5 + BT 4.0 | ^^ | ^^ | | MacBookPro11,2 | ^^ | ^^ | ^^ | | MacBookPro11,3 | ^^ | ^^ | ^^ | | MacBookPro11,4 | Wi-Fi 5 + BT 4.2 | NO | Hardware supports UC.
[**Spoofing required.**](#blacklisted-models) | | MacBookPro11,5 | ^^ | ^^ | ^^ | | MacBookPro12,1 | ^^ | ^^ | ^^ | ::: :::details Mac mini | SMBIOS | WiFi/BT version | UC OOB | Comment | |--------|-----------------|------------|---------| | Macmini3,1 | Wi-Fi 4 + BT 2.1 EDR | NO | Upgrade requires some heavy electrical and case modifications, so instead used a Broadcom USB Bluetooth 4.0+ Dongle. | | Macmini4,1 | ^^ | ^^ | ^^ | | Macmini5,1 | Wi-Fi 4 + BT 4.0 | YES | Universal Control will work. | | Macmini5,2 | ^^ | ^^ | ^^ | | Macmini5,3 | ^^ | ^^ | ^^ | | Macmini6,1 | ^^ | ^^ | ^^ | | Macmini6,2 | ^^ | ^^ | ^^ | | Macmini7,1 | Wi-Fi 5 + BT 4.0 | NO | Hardware supports UC.
[**Spoofing required.**](#blacklisted-models) | ::: :::details iMac | SMBIOS | WiFi/BT version | UC OOB | Comment | |----------|-----------------|------------|---------| | iMac7,1 | Wi-Fi 4 + BT 2.0 EDR | NO | Replace stock AirPort card with an mPCIE + USB Connector Adapter board with a BCM94360CD card | iMac8,1 | ^^ | ^^ | ^^ | | iMac9,1 | Wi-Fi 4 / BT 2.1 EDR | ^^ | ^^ | | iMac10,1 | ^^ | ^^ | ^^ | | iMac11,1 | ^^ | ^^ | ^^ | | iMac11,2 | ^^ | ^^ | ^^ | | iMac11,3 | ^^ | ^^ | ^^ | | iMac12,1 | ^^ | ^^ | Replace stock AirPort card with an mPCIE + USB Connector Adapter board with a BCM943602CD card | iMac12,2 | ^^ | ^^ | ^^ | | iMac13,1 | Wi-Fi 4 + BT 4.0 | YES | Universal Control will work. | | iMac13,2 | ^^ | ^^ | ^^ | | iMac13,3 | ^^ | ^^ | ^^ | | iMac14,1 | Wi-Fi 5 + BT 4.0 | ^^ | ^^ | | iMac14,2 | ^^ | ^^ | ^^ | | iMac14,3 | ^^ | ^^ | ^^ | | iMac14,4 | ^^ | ^^ | ^^ | | iMac15,1 | ^^ | ^^ | ^^ | | iMac16,1 | Wi-Fi 5 + BT 4.2 | NO | Hardware supports UC.
[**Spoofing required.**](#blacklisted-models) | | iMac16,2 | ^^ | ^^ | ^^ | ::: :::details Mac Pro | SMBIOS | WiFi/BT version | UC OOB | Comment | |-----------|-----------------|---------|---------| | MacPro3,1 | Wi-Fi 4 + BT 2.0 EDR | NO | Replace stock AirPort card with an mPCIE Adapter board with a BCM943602CD card | | MacPro4,1 | Wi-Fi 4 + BT 2.1 EDR | ^^ | Replace stock AirPort card with an mPCIE + USB Connector Adapter board with a BCM943602CD card | | MacPro5,1 | ^^ | ^^ | ^^ | | MacPro6,1 | Wi-Fi 5 + BT 4.0 | ^^ | Hardware supports UC.
[**Spoofing required.**](#blacklisted-models) | * Note: Some older Mac Pro configurations may not have shipped with a WiFi card in the base model ::: :::details Xserve ;p | SMBIOS | WiFi/BT version | UC OOB | Comment | |-----------|-----------------|---------|---------| | Xserve2,1 | N/A | NO | Install a PCIe BCM943602CD card | | Xserve3,1 | ^^ | ^^ | ^^ | ::: ## Blacklisted models The following models are blacklisted from using Universal Control by Apple: - MacBookAir7,x - MacBook Air Early 2015 11" / 13" - MacBookPro11,4 - MacBook Pro Mid 2015 15" (Intel Iris) - MacBookPro11,5 - MacBook Pro Mid 2015 15" (dGPU) - MacBookPro12,x - MacBook Pro Early 2015 13" - iMac16,x - iMac Late 2015 21" - Macmini7,x - Mac mini 2014 - MacPro6,x - Mac Pro Late 2013 The hardware in these models are capable of supporting Universal Control, but due to blacklisting, the only solution to use Universal Control on these models is to spoof their SMBIOS. SMBIOS spoofing essentially fools some aspects of macOS to think they are running on a different machine. With SMBIOS Spoofing, the Universal Control handshake recognizes a different SMBIOS and thus grants a blacklisted Mac to connect to other Macs and iPads with Universal Control. | Situation | Condition | Solution | |-----------|-----------|---------| | Mac <-> Mac connection | Monterey-unsupported | No spoofing needed | | Mac <-> iPad connection | Monterey-unsupported | No spoofing needed | | Mac <-> Mac connection | One or both are blacklisted |Spoofing required on blacklisted Macs | | Mac <-> iPad connection | Blacklisted Mac | Spoofing required on blacklisted Mac | :::warning Before we continue, please keep in mind that SMBIOS Spoofing is an advanced feature of OpenCore. Reckless usage of it could potentially break important functionality and leave your installation in a non-working state. Once you boot into a spoofed state, it is highly recommended that you stay spoofed, and avoid booting macOS without OpenCore. ::: ### How to spoof ::: details macOS Sequoia Firstly run OpenCore Legacy Patcher. Then go to **Settings** and **SMBIOS** tab, set SMBIOS Spoof Level to **Moderate**. Set SMBIOS Spoof Model **one listed next to your native model in the table for spoofed models below.** Notice that "Allow native models" and "Allow Native Spoofs" **are NOT** enabled unlike on Monterey, this is on purpose. They are no longer relevant on Sonoma and enabling them will cause boot issues. | Main Settings view | SMBIOS settings | | :--- | :--- | | | | ::: details Table for spoofed models (click to expand) Spoofing to any model with native Sequoia support should work, but these are the earliest Macs natively supported by Sequoia and thus chosen for the sake of simplicity. **Reminder:** Macs that are not listed on this table work without spoofing, including systems that do not natively support Sequoia as long as the other requirements are met, since they aren't blacklisted. | Mac by name | Native SMBIOS | Spoof SMBIOS | |-------------|---------------|--------------| | MacBook Air Early 2015 11" / 13" | MacBookAir7,x | MacBookAir9,1 | | MacBook Pro Early 2015 13" | MacBookPro12,x | MacBookPro15,2 | | MacBook Pro Mid 2015 15" | MacBookPro11,4 / 11,5 | MacBookPro15,2 | | iMac Late 2015 21" | iMac16,x | iMac19,2 | | Mac mini Late 2014 | Macmini7,x | MacMini8,1 | | Mac Pro Late 2013 | MacPro6,x | MacPro7,1 | ::: ::: details macOS Sonoma Firstly run OpenCore Legacy Patcher. Then go to **Settings** and **SMBIOS** tab, set SMBIOS Spoof Level to **Moderate**. Set SMBIOS Spoof Model **one listed next to your native model in the table for spoofed models below.** Notice that "Allow native models" and "Allow Native Spoofs" **are NOT** enabled unlike on Monterey, this is on purpose. They are no longer relevant on Sonoma and enabling them will cause boot issues. | Main Settings view | SMBIOS settings | | :--- | :--- | | | | ::: details Table for spoofed models (click to expand) Spoofing to any model with native Sonoma support should work, but these are the earliest Macs natively supported by Sonoma and thus chosen for the sake of simplicity. **Reminder:** Macs that are not listed on this table work without spoofing, including systems that do not natively support Sonoma as long as the other requirements are met, since they aren't blacklisted. | Mac by name | Native SMBIOS | Spoof SMBIOS | |-------------|---------------|--------------| | MacBook Air Early 2015 11" / 13" | MacBookAir7,x | MacBookAir8,1 | | MacBook Pro Early 2015 13" | MacBookPro12,x | MacBookPro15,2 | | MacBook Pro Mid 2015 15" | MacBookPro11,4 / 11,5 | MacBookPro15,2 | | iMac Late 2015 21" | iMac16,x | iMac19,2 | | Mac mini Late 2014 | Macmini7,x | MacMini8,1 | | Mac Pro Late 2013 | MacPro6,x | MacPro7,1 | ::: ::: details macOS Ventura Firstly run OpenCore Legacy Patcher. Then go to **Settings** and **SMBIOS** tab, set SMBIOS Spoof Level to **Moderate**. Set SMBIOS Spoof Model **one listed next to your native model in the table for spoofed models below.** Notice that "Allow native models" and "Allow Native Spoofs" **are NOT** enabled unlike on Monterey, this is on purpose. They are no longer relevant on Ventura and enabling them will cause boot issues. | Main Settings view | SMBIOS settings | | :--- | :--- | | | | ::: details Table for spoofed models (click to expand) Spoofing to any model with native Ventura support should work, but these are the earliest Macs natively supported by Ventura and thus chosen for the sake of simplicity. **Reminder:** Macs that are not listed on this table work without spoofing, including systems that do not natively support Ventura as long as the other requirements are met, since they aren't blacklisted. | Mac by name | Native SMBIOS | Spoof SMBIOS | |-------------|---------------|--------------| | MacBook Air Early 2015 11" / 13" | MacBookAir7,x | MacBookAir8,1 | | MacBook Pro Early 2015 13" | MacBookPro12,x | MacBookPro14,1 | | MacBook Pro Mid 2015 15" | MacBookPro11,4 / 11,5 | MacBookPro14,3 | | iMac Late 2015 21" | iMac16,x | iMac18,2 | | Mac mini Late 2014 | Macmini7,x | MacMini8,1 | | Mac Pro Late 2013 | MacPro6,x | MacPro7,1 | ::: ::: details macOS Monterey Firstly, run OpenCore Legacy Patcher. Secondly, go to **Settings** then the **App** tab and tick **Allow native models**. [](./images/OCLP-App-Allow-Native-Models.png) Then, go to **SMBIOS** tab, tick **Allow spoofing native Macs**, set SMBIOS Spoof Level to **Moderate**. Set SMBIOS Spoof Model to **one listed next to your native model in the table for spoofed models below.** | Main Settings view | SMBIOS settings | | :--- | :--- | | | | ::: details Table for spoofed models (click to expand) Any model after the list of officially blacklisted Macs should be supported, but these are the earliest Macs with Universal Control support, and thus chosen for the sake of simplicity. **Reminder:** Macs that are not listed on this table work without spoofing, including systems that do not natively support Monterey, as long as the other requirements are met, since they aren't blacklisted. | Mac by name | Native SMBIOS | Spoof SMBIOS | |-------------|---------------|--------------| | MacBook Air Early 2015 11" / 13" | MacBookAir7,x | MacBookAir8,1 | | MacBook Pro Early 2015 13" | MacBookPro12,x | MacBookPro13,1 | | MacBook Pro Mid 2015 15" | MacBookPro11,4 / 11,5 | MacBookPro13,3 | | iMac Late 2015 21" | iMac16,x | iMac18,2 | | Mac mini Late 2014 | Macmini7,x | MacMini8,1 | | Mac Pro Late 2013 | MacPro6,x | MacPro7,1 | ::: **Note:** Unless you are building OpenCore on a different machine than it's targeted for, **do not** change the model in the main settings view. It is important to understand that OCLP targets this model regardless of what you may have spoofed to, as your Mac is still what the Native SMBIOS shows. Lastly, Build and install OpenCore again, and reboot back to the OS. Enable Universal Control as explained in the [Enabling Universal Control section.](#enabling-universal-control) You should now be prompted to log back into iCloud by your Mac. If you get this prompt, you have successfully configured SMBIOS spoofing. Otherwise, verify that you have correctly followed the steps listed above, or ask on the Discord server for further assistance in [#misc-help](https://discord.gg/rqdPgH8xSN). --- ### UPDATE (`docs/UPDATE.md`) # Updating This guide explains how to get fully up to date application, bootloader and patches. ## Updating the application, OpenCore and patches Latest versions of OCLP can download updates by themselves, you will get notified of a new update with the changelog. [You can also manually download the latest release here.](https://github.com/dortania/OpenCore-Legacy-Patcher/releases) After the update, the application asks if you want to update OpenCore and root patches. * If you do not need to change any settings, click "Yes" on the patch update question and follow the procedure to update OpenCore and root patches automatically. * If you do want to change settings, select "No" and do your settings. * In case you selected "No", you will have to manually build and install OpenCore and then manually install new root patches to ensure you're running on the latest OpenCore with your settings and the fixes for on-disk patches. | Update available | App update success, patch update question | | :--- | :--- | | Update Available | Update Successful | #### Checking OCLP and OpenCore versions To check what version of OpenCore bootloader and the Patcher you're currently running, open the OCLP application and navigate to `Settings -> App` and look for "Booted Information". Alternatively you can check the version from Terminal using the following commands. Check the status and version of root patches from `Post Install Volume Patch` section in the main menu. ```bash # OpenCore Version nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:opencore-version # Patcher Version nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:OCLP-Version ``` | Version in app | Version in Terminal | Root patch version | | :--- | :--- | :--- | | Build start | OCLP version | Root Patch Version | ## Preparing OCLP for macOS update It is usually recommended to be on the latest OCLP version for macOS updates. This part details how to prepare OCLP for latest update. ### Major upgrades This part is for major upgrades, such as `Sonoma (14)` -> `Sequoia (15)` 1. Make sure the OCLP app is up to date. 2. After app has updated, rebuild OpenCore to the internal disk to update the bootloader. * You can also update root patches but this part is optional in this stage, as they will be wiped by the update. 2. Download the macOS version you want and create an installer USB drive using OCLP as detailed in the original [Creating macOS Installers](https://dortania.github.io/OpenCore-Legacy-Patcher/INSTALLER.html) guide, then follow the [Booting OpenCore and macOS](https://dortania.github.io/OpenCore-Legacy-Patcher/BOOT.html) guide boot to into the installer on your USB drive. 3. Start macOS installation and follow the process, do not use Disk Utility if you don't want to wipe your disk. 4. After installation, reinstall [root patches](https://dortania.github.io/OpenCore-Legacy-Patcher/POST-INSTALL.html#applying-post-install-volume-patches). **Note:** Major upgrades may work using System Settings but this is not recommended. ### Minor updates This part is for minor updates, which are also called the "dot updates". Such as `12.x`, `13.x` etc. 1. Make sure the OCLP app is up to date. 2. Rebuild OpenCore to the internal disk to update the bootloader. * You can also update root patches but this part is optional in this stage, as they will be wiped by the update. 3. Start update from System Settings. * If your system requires [KDKSupportPkg](https://dortania.github.io/OpenCore-Legacy-Patcher/POST-INSTALL.html#kdk-kernel-debug-kit), OCLP will start downloading it automatically as long as you are connected to the internet and have the [background process](https://dortania.github.io/OpenCore-Legacy-Patcher/PROCESS.html) enabled. 4. Once installed, go into OCLP app and reinstall [root patches](https://dortania.github.io/OpenCore-Legacy-Patcher/POST-INSTALL.html#applying-post-install-volume-patches). ::: warning Important Some systems on Sequoia require [MetallibSupportPkg](https://dortania.github.io/OpenCore-Legacy-Patcher/POST-INSTALL.html#metallibsupportpkg) during root patching after an update, which requires internet connection to download. If OCLP doesn't see internet connection, it will first offer a patch for WiFi only. You will have to reboot, connect to the internet and rerun root patching for the rest of the patches. ::: --- ### VENTURA DROP (`docs/VENTURA-DROP.md`) # macOS Ventura With the release of OpenCore Legacy Patcher v0.5.0 and newer, early support for macOS Ventura has been implemented for most Metal-capable Macs. This page will be used to inform users regarding current issues and will be updated as new patch sets are developed and added to our patcher. ## Newly dropped hardware Ventura's release dropped a large amount of Intel hardware, thus requiring the usage of OpenCore Legacy Patcher on the following models (in addition to previously removed models): * iMac16,1 (21.5-inch, Late 2015) * iMac16,2 (21.5-inch and 21.5-inch 4K, Late 2015) * iMac17,1 (27-inch 5K, Late 2015) * MacBook9,1 (12-inch, Early 2016) * MacBookAir7,1 (11-inch, Early 2015) * MacBookAir7,2 (13-inch, Early 2015) * MacBookPro11,4 (15-inch, Mid 2015, iGPU) * MacBookPro11,5 (15-inch, Mid 2015, dGPU) * MacBookPro12,1 (13-inch, Early 2015) * MacBookPro13,1 (13-inch, Late 2016) * MacBookPro13,2 (13-inch, Late 2016) * MacBookPro13,3 (15-inch, Late 2016) * Macmini7,1 (Late 2014) * MacPro6,1 (Late 2013) ## Current status OpenCore Legacy Patcher supports Ventura for the models below, however some challenges remain. You can find information about them further down on this page. For older hardware, see below sections: * [Current issues](#current-issues) * [AMD Polaris, Vega and Navi support on pre-2019 Mac Pros and pre-2012 iMacs](#amd-polaris-vega-and-navi-support-on-pre-2019-mac-pros-and-pre-2012-imacs) * [USB 1.1 (OHCI/UHCI) Support](#usb-11-ohciuhci-support) The team is doing their best to investigate and fix the aforementioned issues, however no estimated time can be provided. ## Current issues ### AMD Polaris, Vega and Navi support on pre-2019 Mac Pros and pre-2012 iMacs For users with 2008 to 2013 Mac Pros (MacPro3,1-6,1) and 2009 to 2011 iMacs (iMac9,1-12,2), keep in mind that macOS Ventura now requires [AVX2.0 support in the CPU](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2) for native graphics acceleration. Thus while your GPU may be natively supported, you cannot run Ventura officially with these GPUs. * CPUs supporting AVX2.0 are Haswell or newer, which no pre-2019 Mac Pros can be upgraded with. Currently at this time, OpenCore Legacy Patcher only supports patching the AMD Polaris and Vega Graphics stack to no longer require AVX2.0. We're recently received an AMD RX 6600 donation, so hopefully in the future the project can support AMD Navi with pre-Haswell Macs. However, no time estimates can be given. Following GPUs are applicable: | GPU Architecture | Model Families | Supported | | :--- | :--- | :--- | | AMD Polaris | RX 4xx/5xx (10/20 series) | Supported with patching | | AMD Vega | Vega 56/64/VII (10/20 series) | ^^ | | AMD Navi | RX 5xxx/6xxx (10/20 series) | Unsupported | ### USB 1.1 (OHCI/UHCI) Support For Penryn systems and pre-2013 Mac Pros, USB 1.1 support was outright removed in macOS Ventura. While USB 1.1 may seem unimportant, it handles many important devices on your system. These include: * Keyboard and Trackpad for laptops * IR Receivers * Bluetooth Refer to [the troubleshooting page](https://dortania.github.io/OpenCore-Legacy-Patcher/TROUBLESHOOT-HARDWARE.html#keyboard-mouse-and-trackpad-not-working-in-installer-or-after-update) on how to workaround this issue. ### Graphics support and issues Refer to the following links for more information about Legacy Metal and non-Metal support and their respective issues. * [Legacy Metal](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/1008) * [Non-Metal](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/108) ### Resolved issues ::: details Legacy Wireless Support (Resolved in v0.6.0 and newer) For systems that required Root Patches in macOS Monterey to achieve Wireless support, unfortunately macOS Ventura has broken the patch set. Currently the following Wifi cards are unsupported: * Atheros: All models * Broadcom: BCM94328 and BCM94322 The following machines shipped stock with these cards: * iMac12,x and older * Macmini3,1 and older * MacBook5,x and older * MacBookAir2,1 and older * MacBookPro7,1 and older * MacBookPro6,x is exempt * MacPro5,1 and older Currently BCM943224, BCM94331, BCM94360 and BCM943602 are still fully supported by OpenCore Legacy Patcher. Consider upgrading to these cards if possible. ::: ::: details Non-Metal Graphics Acceleration (Resolved in v0.6.0 and newer) Regarding non-Metal, the team is hard at work to get non-Metal working, however this is our greatest challenge since Big Sur. Apple has made significant changes to the graphics stack in order to facilitate fancy effects, and in particularly, Stage Manager. We will update you as we work on development, however, now is not the best time to ask about ETAs. The following GPUs are applicable: * NVIDIA: * Tesla (8000 - 300 series) * AMD: * TeraScale (2000 - 6000 series) * Intel: * Iron Lake * Sandy Bridge (2000 - 3000 series) The following machines shipped stock with an unsupported GPU: * iMac7,1 - iMac12,x * MacBook5,1 - MacBook7,1 * MacBookAir2,1 - MacBookAir4,x * MacBookPro4,1 - MacBookPro8,x * Macmini3,1 - Macmini5,x * MacPro3,1 - MacPro5,1 * Xserve2,1 - Xserve3,1 --- ### WINDOWS (`docs/WINDOWS.md`) # Installing Windows in UEFI Mode Modern versions of Windows officially support two types of firmware: UEFI and BIOS. Users may want to boot Windows through the OCLP Bootpicker, but only UEFI Installations of Windows will show up in the OCLP Bootpicker. Many older Macs do not "officially" support UEFI Windows installations, leading to installation failures and strange behaviour, but OCLP can be used to prevent almost all of these issues. ::: warning When booting Windows with OpenCore, it's highly recommended to create a new 200MB **MS-DOS (FAT)** partition in Disk Utility to install OpenCore in. This will prevent Windows from overwriting OpenCore with its own bootloader in the EFI partition and causing boot issues. :::: ## Minimum Requirements This guide will focus on the installation of modern Windows (10/11) without using Boot Camp Assistant. * Due to hardware and firmware limitations, UEFI Windows installations are only recommended on the following machines: * 2015 MacBook or newer (`MacBook8,x`+) * 2011 MacBook Air or newer (`MacBookAir4,x`+) * 2011 MacBook Pro or newer (`MacBookPro8,x`+) * 2011 Mac mini or newer (`Macmini5,x`+) * 2009* Mac Pro or newer (`MacPro4,1`+), upgraded GPU is preferred * 2010 iMac or newer (`iMac11,x`+), upgraded GPU is preferred * 2009* Xserve (`Xserve3,1`), upgraded GPU is preferred *`MacPro4,1`, `MacPro5,1`, and `Xserve3,1` systems experience issues with the Windows installer, follow the DISM installation section for instructions. If your machine is not listed, UEFI Windows will likely still install, but you may face stability/driver issues. ## Disk Partitioning and Formatting The following is required for installation: * 8GB+ USB Drive for the Windows installer * 30GB+ Free Space on an existing drive / empty drive for the Windows installation ### Formatting the USB Drive Open Disk Utility in macOS and format the USB Drive as ExFat with the Master Boot Record scheme: ### Formatting the Target Drive Next, select the drive you wish to install Windows in Disk Utility on and partition it as ExFat (If formatting the entire drive, ensure it's using the GUID Partition Table scheme): :::warning Incorrectly erasing your drive can lead to data loss! Please verify that you are erasing the correct drive/partition. ::: If you plan to use the same hard drive for macOS and Windows, we recommend creating a dedicated partition just for OpenCore. This lets Windows have the ESP to itself and OpenCore can stay within it's own bubble. Recommended size is 200MB and the partition format **must** be FAT32 for OpenCore to operate correctly. You will next want to install OpenCore onto the new partition, either moving from the ESP with [MountEFI](https://github.com/corpnewt/MountEFI) or rerunning the OpenCore-Patcher.app * Note 1: For machines with dedicated drives for Windows, having different partitions for OpenCore is not required. * Note 2: Having different partitions for OpenCore is not required if the Windows boot files detected by the stock Bootpicker are removed. See "Removing the Windows option from the stock bootpicker" for further information. * Note 3: We recommend uninstalling OpenCore from the ESP/EFI Partition when you create this new OpenCore partition to avoid confusion when selecting OpenCore builds in the Mac's boot picker. ## Creating the Windows Installer The latest Windows installation images can be downloaded from Microsoft using the following links: * [Download Windows 10 Disc Image (ISO File)](https://www.microsoft.com/en-ca/software-download/windows10ISO) * [Download Windows 11 Disc Image (ISO File)](https://www.microsoft.com/en-ca/software-download/windows11) Once the file is downloaded, mount the .iso image: Then open terminal and use the `rsync` command with the disk image set as the source and your USB drive set as the target. (Replace "CCCOMA_X64" with the mounted image's partition name, and replace "InstallWin10" with your USB Drive's name). ``` rsync -r -P /Volumes/CCCOMA_X64/ /Volumes/InstallWin10 ``` The `rsync` command will take some time, so get some coffee and sit back. Once finished, the root of the USB drive should look as follows: * Ensure that these folders and files are in the root of the USB drive, otherwise the USB will not boot. ## Installation Process Once you reboot your machine, you should see a new boot option in the OCLP Bootpicker labelled as "EFI Boot" or "Windows". It may or may not have the Boot Camp icon. :::warning If you aren't booted into OCLP, you may see **two** boot options labelled "Windows" and "EFI Boot". Do not choose either of the options and boot into OCLP to continue. ::: ### Installation: Microsoft Method Once booted into the Windows installer, proceed as you normally would on any Windows computer. If you see an error message containing “Windows could not prepare the computer to boot into the next phase of installation”, please follow the next portion of this guide (DISM Installation). ::: details Installing Windows 11 If you are installing Windows 11, you will need to [modify the Windows Setup](https://www.bleepingcomputer.com/news/microsoft/how-to-bypass-the-windows-11-tpm-20-requirement/) to allow installation on unsupported machines. ::: ### Installation: DISM Deployment Method Once booted into the Windows installer, proceed as you normally would until you reach the "Where do you want to install Windows" disk formatting section. When you are prompted to select a drive, select your desired partition and delete it using "Delete". If you want to install Windows to an empty drive, erase every partition currently on the desired drive. After your drive/partition is erased, press "New" to create the Windows system partitions. You will be prompted to confirm the creation of the system partitions, press "OK". Once the partitions are created, select the main (largest) partition and press "Format". This will format the partition using the NFTS file system. After the installer formats the partition, open up the Command Prompt by pressing SHIFT + F10. Then run the `diskpart` command, and `list vol`. This will produce a list of volumes in your system, make sure to keep track of the drive letters of the main Windows partition (largest, NTFS), the EFI partition (100MB, FAT32), and the Windows installer (Usually Drive D). Run `exit` to close diskpart Now, get a list of available Windows editions by running `dism /Get-WimInfo /WimFile:D:\Sources\install.wim` (substituting D with the Installer Drive Letter). This guide will use Option 6 for Windows 10 Pro. You can now start the deployment process. Run `dism /Apply-Image /ImageFile:D:\Sources\install.wim /index:6 /ApplyDir:E:`, replacing "D" with the Installer Drive Letter, "6" with the Windows edition option, and "E" with the Windows Partition Drive Letter. Once `dism` finishes its thing, run `bcdboot E:\Windows`, substituting "E" for the drive letter of the main Windows partition to create the boot files. Windows is now installed. It should be recognized as "EFI Boot" or "Windows" with a Boot Camp icon in the OCLP Bootpicker. :::warning After the boot files are created, **DO NOT** reboot if you are using a MacPro4,1, MacPro5,1, or Xserve3,1 system! A bug in the Windows bootloader exists that will completely brick the system if it is loaded through the stock bootpicker. See the "Installation: Removing the Windows option from the stock bootpicker" section for a workaround. ::: ### Installation: Removing the Windows option from the stock bootpicker Removing the Windows boot option from the stock bootpicker is **HIGHLY RECOMMENDED** on MacPro4,1, MacPro5,1, and Xserve3,1 systems in order to prevent Secure Boot NVRAM corruption and bricking. Start up a command prompt window in the Windows Setup environment by running `cmd`. Next, enter the EFI Folder by running `C:`, substituting "C" for the EFI Partition Drive Letter. Then run `cd EFI` to enter the EFI Partition. Then, run `rmdir Boot /S /Q` to remove the boot files that can be detected by the stock Bootpicker. The OCLP Picker will still be able to detect and boot Windows. You can verify that the `Boot` folder is removed by running the `dir` command: If, for whatever reason, you are not able to remove the boot files from the Windows setup, shut down your system, boot into macOS, mount your EFI partition with [MountEFI](https://github.com/corpnewt/MountEFI), and remove the `Boot` folder (it should have a recent file modification date, and contain `Bootx64.efi`). ## Post-Installation ### Installing Boot Camp Software To get started, download the Brigadier utility from the following link: * [Download Brigadier](https://github.com/timsutton/brigadier/releases/download/0.2.4/brigadier.exe) Once Brigadier is downloaded, move it to your desktop for easy access. Open up a command prompt window as a standard user and run `cd desktop`. Then run `.\brigadier.exe --model=MODEL1,1`, replacing "MODEL1,1" with your machine's SMBIOS model. Once the Boot Camp software is downloaded, you can install it by executing `Setup.exe` or `\Drivers\Apple\BootCamp.msi` (`BootCamp64.msi` if present). ### Installing Boot Camp 6 softare on unsupported machines To get started, download the Brigadier utility from the following link: * [Download Brigadier](https://github.com/timsutton/brigadier/releases/download/0.2.4/brigadier.exe) Once Brigadier is downloaded, move it to your desktop for easy access. Open up a command prompt window as a standard user and run `cd desktop`. Then run `.\brigadier.exe --model=MacPro7,1`. This will download the latest BootCamp 6 package. Once the Boot Camp software is downloaded, you can install Boot Camp 6 by executing `\Drivers\Apple\BootCamp.msi` in an administrator command prompt window. ## Troubleshooting ### "This version of Boot Camp is not intended for this computer model." If you built OpenCore with Moderate or higher SMBIOS spoofing, you'll get an error when trying to install Boot Camp drivers. You can solve this by either rebuilding OpenCore with a lower spoof level, or running the installer from `Drivers/Apple/BootCamp.msi`. | Setup.exe | BootCamp.msi | | :--- | :--- | | | | ::: details BootCamp.msi quirks If needed, you can run it from the command line as administrator: ``` set __COMPAT_LAYER=WIN7RTM && start \path\to\BootCamp\Drivers\Apple\Bootcamp.msi' ``` Make sure to substitute `\path\to` with the location of the Boot Camp folder. You can also open `Properties` on the file to change the compatibility to `Previous version of Windows` in case you have Boot Camp 4.0 drivers (the above command does this already.) ::: ### iMac12,x Bluescreen after driver installation Intel's iGPU drivers for the HD 3000 series do not support UEFI booting in Windows. The recommended solution is to simply disable the iGPU: [iMac 12,1 Windows 10 Boot Loop – Fix Intel Graphics issue](https://zzq.org/?p=39) ### NVIDIA Tesla Black Screen after driver installation The NVIDIA Tesla GPUs found in 2008-2010 Macs do not support UEFI booting in Windows. You cannot use UEFI Windows without low-level patching on these machines. --- --- METRICS --- - Files Extracted: 32 - Estimated Token Budget: ~47723 tokens - Canonical Reference: https://codewiki.google/github.com/dortania/OpenCore-Legacy-Patcher