OSX-KVM on GitHub (kholia/OSX-KVM)

OSX-KVM README

Note

This README.md documents the process of creating a Virtual Hackintosh system.

Note: All blobs and resources included in this repository are re-derivable (all instructions are included!).

:green_heart: Looking for commercial support with this stuff? I am available over email for a chat for commercial support options only. Note: Project sponsors get access to the Private OSX-KVM repository, and direct support.

Struggling with Content Caching stuff? We can help.

Working with Proxmox and macOS:

See Nick's blog for sure
Here’s a more up-to-date version for Proxmox OpenCore-ISO

Yes, we support offline macOS installations now - see this document 🎉

Contributing Back

This project can always use your help, time and attention. I am looking for help (pull-requests!) with the following work items:

Documentation around running macOS on popular cloud providers (Hetzner, GCP, AWS). See the Is This Legal? section and associated references.
Document (share) how you use this project to build + test open-source projects / get your stuff done.
Document how to use this project for XNU kernel debugging and development.
Document the process to launch a bunch of headless macOS VMs (build farm).
Document usage of munki to deploy software to such a build farm.
Enable VNC + SSH support out of the box or more easily.
Robustness improvements are always welcome!
(Not so) crazy idea - automate the macOS installation via OpenCV.

Requirements

A modern Linux distribution. E.g. Ubuntu 24.04 LTS 64-bit or later.
QEMU >= 8.2.2
A CPU with Intel VT-x / AMD SVM support is required (grep -e vmx -e svm /proc/cpuinfo)
A CPU with SSE4.1 support is required for >= macOS Sierra
A CPU with AVX2 support is required for >= macOS Ventura

Note: Older AMD CPU(s) are known to be problematic but modern AMD Ryzen processors work just fine (even for macOS Sonoma).

Installation Preparation

Install QEMU and other packages.

sudo apt-get install qemu-system uml-utilities virt-manager git \
    wget libguestfs-tools p7zip-full make dmg2img tesseract-ocr \
    tesseract-ocr-eng genisoimage vim net-tools screen -y

This step may need to be adapted for your Linux distribution.

Clone this repository on your QEMU system. Files from this repository are used in the following steps.
```
cd ~

git clone --depth 1 --recursive https://github.com/kholia/OSX-KVM.git

cd OSX-KVM
```
Repository updates can be pulled via the following command:
```
git pull --rebase
```
This repository uses rebase based workflows heavily.

KVM may need the following tweak on the host machine to work.

sudo modprobe kvm; echo 1 | sudo tee /sys/module/kvm/parameters/ignore_msrs

To make this change permanent, you may use the following command. Use lscpu if you are not sure.

sudo cp kvm.conf /etc/modprobe.d/kvm.conf  # for intel boxes only

sudo cp kvm_amd.conf /etc/modprobe.d/kvm.conf  # for amd boxes only

Add user to the kvm and libvirt groups (might be needed).

sudo usermod -aG kvm $(whoami)
sudo usermod -aG libvirt $(whoami)
sudo usermod -aG input $(whoami)

Note: Re-login after executing this command.

Fetch macOS installer.
```
./fetch-macOS-v2.py
```
You can choose your desired macOS version here. After executing this step, you should have the BaseSystem.dmg file in the current folder.

ATTENTION: Let >= Big Sur setup sit at the Country Selection screen, and other similar places for a while if things are being slow. The initial macOS setup wizard will eventually succeed.

Sample run:
```
$ ./fetch-macOS-v2.py
1. High Sierra (10.13)
2. Mojave (10.14)
3. Catalina (10.15)
4. Big Sur (11.7)
5. Monterey (12.6)
6. Ventura (13)
7. Sonoma (14) - RECOMMENDED
8. Sequoia (15)
9. Tahoe (26)

Choose a product to download (1-9): 7
```
Note: Modern NVIDIA GPUs are supported on HighSierra but not on later versions of macOS.
Convert the downloaded BaseSystem.dmg file into the BaseSystem.img file.
```
dmg2img -i BaseSystem.dmg BaseSystem.img
```
Create a virtual HDD image where macOS will be installed. If you change the name of the disk image from mac_hdd_ng.img to something else, the boot scripts will need to be updated to point to the new image name.
```
qemu-img create -f qcow2 mac_hdd_ng.img 256G
```
NOTE: Create this HDD image file on a fast SSD/NVMe disk for best results.
Now you are ready to install macOS 🚀

Installation

CLI method (primary). Just run the OpenCore-Boot.sh script to start the installation process.
```
./OpenCore-Boot.sh
```
Note: This same script works for all recent macOS versions.
Use the Disk Utility tool within the macOS installer to partition, and format the virtual disk attached to the macOS VM. Use APFS (the default) for modern macOS versions.
Go ahead, and install macOS 🙌
(OPTIONAL) Use this macOS VM disk with libvirt (virt-manager / virsh stuff).
- Edit macOS-libvirt-Catalina.xml file and change the various file paths (search for CHANGEME strings in that file). The following command should do the trick usually.
```
sed "s/CHANGEME/$USER/g" macOS-libvirt-Catalina.xml > macOS.xml

virt-xml-validate macOS.xml
```
- Create a VM by running the following command.
```
virsh --connect qemu:///system define macOS.xml
```
- If needed, grant necessary permissions to libvirt-qemu user,
```
sudo setfacl -m u:libvirt-qemu:rx /home/$USER
sudo setfacl -R -m u:libvirt-qemu:rx /home/$USER/OSX-KVM
```
- Launch virt-manager and start the macOS virtual machine.

Headless macOS

Use the provided boot-macOS-headless.sh script.
```
./boot-macOS-headless.sh
```

Setting Expectations Right

Nice job on setting up a Virtual Hackintosh system! Such a system can be used for a variety of purposes (e.g. software builds, testing, reversing work), and it may be all you need, along with some tweaks documented in this repository.

However, such a system lacks graphical acceleration, a reliable sound sub-system, USB 3 functionality and other similar things. To enable these things, take a look at our notes. We would like to resume our testing and documentation work around this area. Please reach out to us if you are able to fund this area of work.

It is possible to have 'beyond-native-apple-hw' performance but it does require work, patience, and a bit of luck (perhaps?).

Post-Installation

See networking notes on how to setup networking in your VM, outbound and also inbound for remote access to your VM via SSH, VNC, etc.
To passthrough GPUs and other devices, see these notes.
Need a different resolution? Check out the notes included in this repository.
Trouble with iMessage? Check out the notes included in this repository.
Highly recommended macOS tweaks - https://github.com/sickcodes/osx-optimizer

Is This Legal?

The "secret" Apple OSK string is widely available on the Internet. It is also included in a public court document available here. I am not a lawyer but it seems that Apple's attempt(s) to get the OSK string treated as a trade secret did not work out. Due to these reasons, the OSK string is freely included in this repository.

Please review the 'Legality of Hackintoshing' documentation bits from Dortania's OpenCore Install Guide.

Gabriel Somlo also has some thoughts on the legal aspects involved in running macOS under QEMU/KVM.

You may also find this 'Announcing Amazon EC2 Mac instances for macOS' article interesting.

Note: It is your responsibility to understand, and accept (or not accept) the Apple EULA.

Note: This is not legal advice, so please make the proper assessments yourself and discuss with your lawyers if you have any concerns (Text credit: Dortania)

Motivation

My aim is to enable macOS based educational tasks, builds + testing, kernel debugging, reversing, and macOS security research in an easy, reproducible manner without getting 'invested' in Apple's closed ecosystem (too heavily).

These Virtual Hackintosh systems are not intended to replace the genuine physical macOS systems.

Personally speaking, this repository has been a way for me to 'exit' the Apple ecosystem. It has helped me to test and compare the interoperability of Canon CanoScan LiDE 120 scanner, and Brother HL-2250DN laser printer. And these devices now work decently enough on modern versions of Ubuntu (Yay for free software). Also, a long time back, I had to completely wipe my (then) brand new MacBook Pro (Retina, 15-inch, Late 2013) and install Xubuntu on it - as the OS X kernel kept crashing on it!

Backstory: I was a (poor) student in Canada in a previous life and Apple made my work on cracking Apple Keychains a lot harder than it needed to be. This is how I got interested in Hackintosh systems.

23.7K ·GitHub

OSX-KVM

What is this?

Scripts and OpenCore configuration for running macOS as a virtual machine under QEMU/KVM on a Linux host, supporting recent macOS versions such as Monterey, Ventura and Sonoma.

Is this a ready-made app or a set of scripts I run myself?

Not an app: it is a set of shell scripts, boot configs and notes. You clone the repo, prepare the installer image and launch the VM with OpenCore-Boot.sh, which QEMU boots via OpenCore.

How do I go from zero to a running macOS desktop?

No Mac needed: install QEMU and other packages, clone the repo, run the fetch step to get BaseSystem.dmg, convert it to BaseSystem.img, create a virtual HDD on a fast SSD, then run OpenCore-Boot.sh and install macOS.

What hardware and software does my machine need for this?

A modern 64-bit Linux distro (Ubuntu 24.04 LTS or later), QEMU 8.2.2+, and a CPU with Intel VT-x or AMD SVM. SSE4.1 is needed for Sierra and later, AVX2 for Ventura and later; old AMD CPUs are problematic, but modern Ryzen works fine.

What am I giving up compared to a real Mac?

Graphical acceleration, a reliable sound subsystem and USB 3 are missing out of the box. Beyond-native performance is possible but takes work, patience and a bit of luck; the repo notes cover the tweaks.

Can I run it on a headless server?

Yes — use the provided boot-macOS-headless.sh script, and the networking notes explain how to set up inbound SSH or VNC access for remote use.

Can I install macOS fully offline?

Yes. The README announces support for offline macOS installations and links to a document describing the OpenCore-ISO method.

Is running macOS this way legal, and is there a license?

There is no license file; the author includes Apple's OSK string, arguing it is freely available via a public court document, and defers legality questions to Dortania's write-ups. Accepting (or not) the Apple EULA is your responsibility.

Can I pass my GPU through to the VM?

Passthrough of GPUs and other devices is covered by dedicated notes in the repo. Caveat: modern NVIDIA GPUs only work up to High Sierra, not on later macOS versions.

What do people use these macOS VMs for?

Per the author: educational tasks, software builds and testing, XNU kernel debugging, reversing and macOS security research — reproducibly and without Apple hardware. He stresses such systems are not meant to replace real Macs.

Why did the author build this?

He wanted an easy, reproducible way to do macOS security research and testing without getting invested in Apple's closed ecosystem. As a poor student in Canada, Apple made his work on cracking Apple Keychains harder than needed, and Hackintosh systems became his way to exit the ecosystem.

Which macOS versions does it support?

The OpenCore-Boot.sh script is described as working for all recent macOS versions, and the fetch step lets you choose which one to download. Monterey, Ventura and Sonoma are highlighted, with Catalina and Tahoe also among the supported targets in the repo topics.

Is there anyone to help if setup fails?

Free support is deliberately limited: the author answers only commercial (paid) support enquiries to avoid spammy issues. Project sponsors get access to a private repository and direct support.

What are similar projects?

macOS-Simple-KVM, macos, darwin-vm, ProxmoxVE, windows, motor-os, quickemu, qemu

Which topics is it in?

macos-installer, hackintosh, proxmox, osx, qemu, kvm, virtual-machine, emulation, homelab, kernel, virtualization, debugging

Creator: kholia
Size: 165.2 MB
Stars: 23.7K
Updated: CommitJan 26
Age: 10y
Commits · 90 Days