OSX-Hyper-V

A Hackintosh project implementing the MacHyperVSupport package for Windows Hyper-V, built on top of the OpenCore bootloader and OCE-Build build manager.

⚡Quick Links

• Current Progress
  • macOS Version Support
• Getting Started
  • 1. Clone this repository using git
  • 2. Configure OpenCore for your hardware
    • Intel
    • AMD
  • 3. Build this repository using OCE-Build
  • 4. Setting up Hyper-V
  • 5. Using this EFI with macOS
  • 6. Troubleshooting
• Contributing
• License
• Credits

⚙️ Current Progress

Refer to the CHANGELOG or SemVer board for changes implemented per release version.

macOS Version Support:

[!NOTE] Installations of OS X Tiger (10.4) to Snow Leopard (10.6) are not possible directly. It is recommended to first install a newer version of macOS and restore to the desired version using a disk image provided by Acidanthera.

You can also find other past InstallAssistant.dmg archives on Archive.org.

Supported versions below include macOS versions 10.4 to 26.0.

macOS Version	Status		Minimum version	Maximum version
Tahoe	🚧	In Progress.	(None)	(Latest)
Sequoia	✅	Supported.	(None)	(Latest)
Sonoma	✅	Supported.	(None)	(Latest)
Ventura	✅	Supported.	(None)	(Latest)
Monterey	✅	Supported.	(None)	(Latest)
Big Sur	✅	Supported.	(None)	(Latest)
Catalina	✅	Supported.	(None)	(Latest)
Mojave	✅	Supported.	(None)	(Latest)
High Sierra	✅	Supported.	(None)	(Latest)
Sierra	✅	Supported.	(None)	(Latest)
El Capitan	✅	Supported.	(None)	(Latest)
Yosemite	✅	Supported.	(None)	(Latest)
Mavericks	✅	Supported.	(None)	(Latest)
Mountain Lion	✅	Supported.	(None)	(Latest)
Lion	✅	Supported.	(None)	(Latest)
Snow Leopard	🚧	Supported.	(None)	(Retail)
Leopard	🚧	Supported.	(None)	(Retail)
Tiger	🚧	Supported.	(None)	(Retail)

Refer to HyperV-versions.md for a complete breakdown of macOS compatibility with Windows Client, Server, and Hyper-V versions.

✨ Getting Started

If you opt to use one of the pre-built releases from this repository, you can skip to 2. Configure OpenCore for your hardware to setup OpenCore for your specific CPU, and then proceed to 4. Setting up Hyper-V to create a new virtual machine.

Those who wish to build this project from source can follow the below steps to clone this repository, build the EFI, and setup Hyper-V.

1. Clone this repository using Git

To clone this repository, run the below command:

git clone https://github.com/Qonfused/OSX-Hyper-V
cd OSX-Hyper-V

[!TIP] Alternatively, you can use the curl command to download and extract the tarball from GitHub:

iwr https://github.com/Qonfused/OSX-Hyper-V/archive/refs/heads/main.zip -OutFile OSX-Hyper-V-main.zip | tar -xf OSX-Hyper-V-main.zip
rm OSX-Hyper-V-main.zip
cd OSX-Hyper-V-main

2. Configure OpenCore for your hardware

[!NOTE] MacHyperVSupport requires Windows Server 2012 R2 / Windows 8.1 or higher. Windows Server 2016 is currently unsupported.

As Hyper-V is a type-1 hypervisor, it requires a compatible CPU to run macOS. This means that any passed-through hardware needs to be supported or patched as you would on a bare-metal Hackintosh.

There is no GPU acceleration by default, which means any graphics-related tasks will be driven by the CPU and will be slow. To get GPU acceleration, you will need to use Discrete Device Assignment (DDA) to pass through a supported GPU for acceleration.

[!IMPORTANT] Unlike bare metal, iGPU/APUs are not visible to the VM by default and require DDA support for GPU passthrough. Additionally, most discrete GPUs, even if natively supported, may not work if passed through with DDA. Refer to the limitations section for an overview of current support in Hyper-V.

For a general overview of hardware support, refer to the CPU Support and GPU Support sections of the Dortania guide for a breakdown of hardware support by macOS version.

To setup OpenCore for your specific CPU, follow the Intel or AMD section of the Dortania Install guide for your CPU family. Ignore any USB mapping, firmware, or motherboard-specific sections as they are not relevant to Hyper-V (which provides its own virtualized hardware).

See the below sections for a breakdown of hardware support and Hyper-V-specific configuration.

Intel

[!NOTE] For Intel Tiger Lake and newer (11th Gen and newer), you can follow the Dortania install guide for Comet Lake.

You'll need to spoof your CPU as Comet Lake by using the below CPUID patch:

Kernel:
  Emulate:
    Cpuid1Data: Data | <55 06 0A 00 00 00 00 00 00 00 00 00 00 00 00 00>
    Cpuid1Mask: Data | <FF FF FF FF 00 00 00 00 00 00 00 00 00 00 00 00>

Add this to the config.yml file under the Kernel -> Emulate section or manually to the generated config.plist file under EFI/OC/config.plist.

See Cpuid1Data for other available CPUID patches for better XCPM support.

Below is a list of supported CPU generations and their initial and latest supported macOS versions:

Desktop CPUs:

Mobile CPUs:

AMD

[!IMPORTANT] AMD CPUs require the Kernel -> Emulate -> DummyPowerManagement option to be enabled in the config.plist as AMD does not have a native power management driver in macOS:

Kernel:
  Emulate:
    DummyPowerManagement:   Boolean | true

Below is a list of supported CPU generations and their initial and latest supported macOS versions:

In addition to AMD kernel patches (for AMD CPU families 15h, 16h, 17h and 19h), the below kernel patch is required for High Sierra and above:

Kernel:
  Patch:
    - Arch:                 String  | "x86_64"
      Base:                 String  | "_cpu_syscall_init"
      Comment:              String  | "flagers - kill invalid wrmsr | 10.13+"
      Count:                Number  | 3
      Find:                 Data    | "0F30"
      Identifier:           String  | "kernel"
      MaxKernel:            String  | ""
      MinKernel:            String  | "17.0.0"
      Replace:              Data    | "9090"

You can also manually add the below plist entry to your config.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Kernel</key>
    <dict>
        <key>Patch</key>
        <array>
            <dict>
                <key>Arch</key>
                <string>x86_64</string>
                <key>Base</key>
                <string>_cpu_syscall_init</string>
                <key>Comment</key>
                <string>flagers - kill invalid wrmsr | 10.13+</string>
                <key>Count</key>
                <integer>3</integer>
                <key>Enabled</key>
                <true/>
                <key>Find</key>
                <data>DzA=</data>
                <key>Identifier</key>
                <string>kernel</string>
                <key>Limit</key>
                <integer>0</integer>
                <key>Mask</key>
                <data></data>
                <key>MaxKernel</key>
                <string></string>
                <key>MinKernel</key>
                <string>17.0.0</string>
                <key>Replace</key>
                <data>kJA=</data>
                <key>ReplaceMask</key>
                <data></data>
                <key>Skip</key>
                <integer>0</integer>
            </dict>
        </array>
    </dict>
</dict>
</plist>

[!NOTE] When applying the AMD kernel patches, choose a core count matching the number of cores assigned to the VM when configuring the CPU core count (i.e. the algrey - Force cpuid_cores_per_package) patches.

For example, on a 6-Core AMD Ryzen 9600X, you may find it helpful to assign 6 cores to the VM and use 06 for the cpuid_cores_per_package patch. If you encounter issues booting when assigning 6 cores, try assigning 8 cores instead and using 08 for the cpuid_cores_per_package patch (see #37).

[!TIP] You can use the amd.ps1 script to automatically generate these AMD patches for your CPU by running the below command:

.\scripts\amd.ps1 --cpu <core_count>

Notice that this requires the --cpu option to be set to the number of cores assigned to the VM.

3. Build this repository using OCE-Build

This project uses OCE-Build to automatically version and build this repository's EFI.

[!IMPORTANT] To run powershell scripts, you may need to set your execution policy using:

Set-ExecutionPolicy RemoteSigned

To build this project's EFI, run one of the below commands at the root of the project:

# Build for macOS 10.8 and newer
.\scripts\build.ps1

# Build for macOS 10.7 and older
.\scripts\build.ps1 --legacy

# Build for macOS 10.4 - 10.5, 10.6 if running in 32-bit mode
.\scripts\build.ps1 --legacy --32-bit

This will create a new dist/ directory containing the EFI.vhdx virtual disk and a dist/Scripts/ directory containing various scripts for creating and configuring the virtual machine.

4. Setting up Hyper-V

First check that you've enabled Hyper-V before proceeding.

• You can enable the Hyper-V role by running the below command in PowerShell as administrator:

  Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
  

• After rebooting, you can check that you've successfully enabled Hyper-V by running:

  Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V
  

[!TIP] After building or downloading this project's EFI, you can run the create-virtual-machine.ps1 script to quickly setup a new virtual-machine.

For example, from a local build of this project:

# Use the latest version of macOS (cpu=2 cores, ram=8 GB, size=50 GB)
.\dist\Scripts\create-virtual-machine.ps1 -name "My New Virtual Machine"

# Use an older version of macOS (cpu=4 cores, ram=16 GB, size=128 GB)
.\dist\Scripts\create-virtual-machine.ps1 -name "Catalina" -version 10.15 -cpu 4 -ram 16 -size 128

or from a downloaded release:

cd ~/Downloads/EFI-1.0.0-64-bit-DEBUG # Scripts are packaged with releases

# Use the latest version of macOS (cpu=2 cores, ram=8 GB, size=50 GB)
.\Scripts\create-virtual-machine.ps1 -name "My New Virtual Machine"

# Use an older version of macOS (cpu=4 cores, ram=16 GB, size=128 GB)
.\Scripts\create-virtual-machine.ps1 -name "Catalina" -version 10.15 -cpu 4 -ram 16 -size 128

[!IMPORTANT] Newer macOS versions (Big Sur and newer) require 6-8 GB of RAM to boot the installer. If you are using an older version of macOS, you can use less RAM (4 GB is the minimum).

Below outline the steps to manually create a new virtual machine for macOS:

i. Create a boot VHDX disk

Format a small (1GB) FAT32 disk initialized with GPT (GUID partition table) and mount it. This will serve as the boot partition for your macOS virtual machine and contain the OpenCore EFI folder.

• Choose one of three ways of creating VHD/VHDX disks:

  • (A) Hyper-V Manager - Navigate to Action > New > Hard Disk.
    

    • Hard disks are located under C:\ProgramData\Microsoft\Windows\Virtual Hard Disks\.
    • You can mount a VHD/VHDX disk by right clicking on the file and selecting Mount.
    • You can unmount by right-clicking on the mounted disk and selecting Eject.

  • (B) Disk Management - Navigate to Action > Create VHD.
    

    • Make sure to initialize the disk as GPT and create a new FAT32 partition.
    • You can mount a VHD/VHDX disk with Action > Attach VHD.
    • You can unmount by right-clicking on the volume and selecting Detach VHD.

  • (C) Powershell - Create a new VHD/VHDX disk with the New-VHD command.

    (Powershell command)

    # Run this command in PowerShell as Administrator
    
    $vhdpath = "$env:USERPROFILE\Desktop\EFI.vhdx"
    $vhdsize = 1GB
    $vhdpart = "GPT"
    $vhdfs = "FAT32"
    New-VHD -Path $vhdpath -Dynamic -SizeBytes $vhdsize |
      Mount-VHD -Passthru |
      Initialize-Disk -PartitionStyle $vhdpart -Confirm:$false -Passthru |
      New-Partition -AssignDriveLetter -UseMaximumSize |
      Format-Volume -FileSystem $vhdfs -Confirm:$false -Force
    

Move the EFI folder (the whole folder) to the root of the VHDX disk.

• You should be left with an EFI/ folder at the root of your EFI VHDX disk.

ii. Create a macOS installer/recovery VHDX disk

Create or add an installer disk with either of the below methods:

• (A) Download a BaseSystem or Recovery image file directly from Apple using macrecovery.py:
  • Follow the Dortania-Guide for steps on downloading macOS installer images.
  • Move both .chunklist and .dmg files downloaded by macrecovery to your EFI VHDX disk under a new folder named com.apple.recovery.boot. You should be left with both an EFI/ and com.apple.recovery.boot/ folder at the root of your EFI VHDX disk.
• (B) Convert a DMG installer to a VHDX disk with qemu-img:
  • If you already have a DMG installer for macOS (e.g. on Sierra and older), you can convert the installer image to a VHDX disk directly by running qemu-img with the command:

    qemu-img.exe convert -f raw -O vhdx InstallMacOSX.dmg InstallMacOSX.vhdx
    

iii. Creating the macOS Virtual Machine

In the Hyper-V Manager, navigate to Action > New > Virtual Machine.

Configure the below options while going through the wizard:

• Specify Generation: Choose Generation 2.
• Assign Memory: Allocate at least 4096 MB (recommended is 8192 MB for Big Sur and newer).
• Configure Networking: Choose the default network switch.
• Connect Virtual Hard Disk: Name and select the size of the disk to install macOS on.

Once created, right click on your new virtual-machine (under the 'Virtual Machines' section of the window), and select Settings.

Then configure the below options under the Hardware section:

• Navigate to 'Security' and uncheck Enable Secure Boot (disable).
• Navigate to 'SCSI Controller' and add a new hard drive for your EFI VHDX (and installer VHDX if applicable).
  • You'll need to attach your EFI VHDX with a location value of 0 and change the location value for your main virtual hard disk to a different value (e.g. 1 or 2). This is to ensure that the EFI disk is the first disk in the boot order.

5. Using this EFI with macOS

Refer to the Installation Process section of the Dortania Guide. Some additional post-install sections are provided to facilitate with Hyper-V (or project) specifics.

A basic summary of the installation process is as follows:

1. Start the virtual machine and select the EFI (dmg) from the OpenCore boot menu.
   • If you created a separate macOS installer VHDX, this may also show up as macOS Base System (External) or Install macOS Big Sur (External) depending on the version of macOS you are installing.
2. Once the installer loads, open Disk Utility from the Utilities menu.
   • Select the Msft Virtual Disk Media (your main virtual hard disk) from the list of disks.
   • Click Erase to format the disk.
     • Name the disk as desired (e.g., macOS or Macintosh HD, etc.).
     • For macOS 10.13 and newer, use the APFS format. For older versions, use Mac OS Extended (Journaled).
3. Quit Disk Utility and return to the main installer menu.
4. Select Reinstall macOS to start the main installer.
   • Follow the prompts to install macOS on your newly formatted disk.
   • Make sure to target the disk you just formatted (e.g., macOS or whatever you named it), not the EFI disk.
   • Note that this process may take a while (upwards of 30 minutes to 2 hours).
5. Once the installation is complete, the virtual machine will reboot and you should see the OpenCore boot menu again.
   • This may require multiple reboots to install additional components and finalize the installation.
6. Select the newly installed macOS disk (or whatever you named it) from the OpenCore boot menu to boot into macOS.
   • If you are still unable to boot into your macOS installation, you may need to select the installer disk again.
   • You can set this as the default boot entry by holding the Ctrl key while selecting the disk.

The EFI virtual disk created by this project bundles a post-installation script responsible for installing the MacHyperVFramebuffer driver and configuring daemons for additional Hyper-V service support. This is required to support resolution changes and the hardware cursor in macOS.

To run this script, execute the post-install.sh script from the EFI disk located in the Scripts/ directory. For example, you can run the following command in Terminal after booting into the macOS installer:

cd /Volumes/EFI # Change to the EFI disk
bash ./Scripts/post-install.sh

You can also optionally run the optimize-vm.sh script to disable Spotlight indexing, reduce disk I/O, and turn off system animations. This is recommended for virtual machines with CPU-rendered graphics and limited disk performance.

cd /Volumes/EFI # Change to the EFI disk
bash ./Scripts/optimize-vm.sh

6. Troubleshooting

If you encounter issues during the installation or boot process, feel free to create a GitHub issue and provide as much detail as possible about your setup, including:

• The version of macOS you are trying to install.
• The version of Windows you are running Hyper-V on.
• The CPU you are using (e.g. Intel i7-9700K, AMD Ryzen 5 3600, etc.).
• The number of CPU cores and amount of RAM assigned to the virtual machine.
• Any error messages you are seeing in the OpenCore boot menu or during the installation process.

There are however some common issues that you may encounter, outlined below:

• Early reboot after selecting the installer (#[EB.MM.AKM|!] Err(0xE) <- EB.MM.MKP)
  • This usually indicates that the macOS installer does not have enough memory to boot. Make sure you have at least 6-8 GB of RAM for macOS 11 Big Sur and newer, or at least 4 GB for older versions (Catalina and older).
  • See #44 for more details.
• Stuck on vm_shared_region_start_address() or failed lookup: com.apple.dock.fullscreen:
  • Stalling around here usually means the macOS installer GUI couldn't start. You may find other messages related to WindowServer or gui/0 requesting other services (namely logd or recoveryosd), which serve as a hint for this issue.
  • Try restarting and clearing NVRAM (using the Reset NVRAM option in the OpenCore boot menu) to see if that resolves the issue.
  • A good workaround if this issue persists is to instead install macOS Catalina (10.15), and then upgrade to the desired version of macOS after installation. See #53 for details.
• Reboot after installation when selecting installer.
  • This is relatively normal behavior. It may require multiple reboots (selecting the macOS installer each time) to complete the installation process.

Limitations

There are some known limitations with the base configuration for Hyper-V:

• Display Resolution
  • The default virtual display resolution is set to a 1024x768 resolution, but can be reconfigured by modifying the SupportedResolutions entry in MacHyperVFramebuffer's Info.plist file.
  • See issue #6 for more details.
• Graphics Acceleration
  • By default, macOS will run using the MacHyperVFramebuffer synthetic graphics driver, which provides basic graphics support (with 8 MB of video memory). This driver is sufficient for basic tasks, but does not provide hardware acceleration or advanced graphics features.
  • GPU acceleration is possible through Discrete Device Assignment (DDA) using a supported GPU, however there exist a couple major caveats:
    • AMD GPUs (particularly Navi and older GPUs) generally have poor compatibility with macOS through DDA. Natively supported NVIDIA GPUs (using driver v465 or later on Windows) tend to have the best results.
    • GPU patching with Lilu and WhateverGreen is currently not supported (refer to #2299 for tracking). This also applies to other kexts like NootedRed/NootedRX that use Lilu.
• Audio Support
  • By default, Hyper-V does not expose an audio device to macOS.
  • See issue #9 for more details.

[!NOTE] DDA is only available for Windows Server and Microsoft Hyper-V Server versions 2016 and newer. Windows Pro and Windows Enterprise users have no support for DDA with Hyper-V.

iServices

To enable iServices functionality, you can:

1. Generate SMBIOS data with GenSMBIOS

• Follow the Dortania iServices guide to generate new SMBIOS data for your machine.

2. For local builds of this EFI, patch existing SMBIOS data automatically.

• This is automatically patched each time you run a build using the .serialdata file (using existing data or data generated by GenSMBIOS).
• Refer to the .serialdata.example file for an example of the entry format.

🔥 Contributing

Contributions of any size to this project are always welcome!

Refer to CONTRIBUTING.md for instructions (and tips) on making contributions to this project.

⚖️ License

BSD 3-Clause License.

🌟 Credits

• @Goldfish64 for creating and maintaining MacHyperVSupport and it's supporting documentation.
• @ssdsl0126 for testing and discoverying a fix for recoveryOS boot issues on AMD Ryzen 5950x CPUs.