README.md documents the process of creating a
Note: All blobs and resources included in this repository are re-derivable (all instructions are included!).
Private OSX-KVM repository, and direct support.
Content Caching stuff? We can help.
Proxmox and macOS? See Nick's blog for sure.
Yes, we support offline macOS installations now
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
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.
A modern Linux distribution. E.g. Ubuntu 22.04 LTS 64-bit or later.
QEMU >= 6.2.0
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 Mojave
Note: Older AMD CPU(s) are known to be problematic. AMD FX-8350 works but Phenom II X3 720 does not. Ryzen processors work just fine.
KVM may need the following tweak on the host machine to work.
echo 1 | sudo tee /sys/module/kvm/parameters/ignore_msrs
To make this change permanent, you may use the following command.
sudo cp kvm.conf /etc/modprobe.d/kvm.conf # for intel boxes only, after cloning the repo below
Install QEMU and other packages.
sudo apt-get install qemu uml-utilities virt-manager git \ wget libguestfs-tools p7zip-full make dmg2img -y
This step may need to be adapted for your Linux distribution.
Add user to the
libvirtgroups (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.
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.
Fetch macOS installer.
You can choose your desired macOS version here. After executing this step, you should have the
BaseSystem.dmgfile in the current folder.
>= Big Sursetup sit at the
Country Selectionscreen, and other similar places for a while if things are being slow. The initial macOS setup wizard will eventually succeed.
$ ./fetch-macOS-v2.py 1. High Sierra (10.13) 2. Mojave (10.14) 3. Catalina (10.15) 4. Big Sur (11.7) - RECOMMENDED 5. Monterey (12.6) 6. Ventura (13) Choose a product to download (1-6): 4
Note: Modern NVIDIA GPUs are supported on HighSierra but not on later versions of macOS.
Convert the downloaded
BaseSystem.dmgfile into the
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.imgto 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 128G
NOTE: Create this HDD image file on a fast SSD/NVMe disk for best results.
Now you are ready to install macOS
CLI method (primary). Just run the
OpenCore-Boot.shscript to start the installation process.
Note: This same script works for all recent macOS versions.
Disk Utilitytool within the macOS installer to partition, and format the virtual disk attached to the macOS VM.
Go ahead, and install macOS
TIP: Using a non-APFS filesystem is recommended.
(OPTIONAL) Use this macOS VM disk with libvirt (virt-manager / virsh stuff).
macOS-libvirt-Catalina.xmlfile and change the various file paths (search for
CHANGEMEstrings 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
virt-managerand start the
Use the provided boot-macOS-headless.sh script.
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?).
See networking notes to setup guest networking.
I have the following commands present in
#!/usr/bin/env bash sudo ip tuntap add dev tap0 mode tap sudo ip link set tap0 up promisc on sudo ip link set dev virbr0 up sudo ip link set dev tap0 master virbr0
This has been enough for me so far.
Note: You may need to enable the
rc.localfunctionality manually on modern Ubuntu versions. Check out the notes included in this repository for details.
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)
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).
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.