OSX-KVM - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #react #typescript #linux #macos #java #nodejs #windows #kubernetes #security #ios #mcp #openai

OSX-KVM

(★ 23,568)

Run macOS on QEMU/KVM. With OpenCore + Monterey + Ventura + Sonoma support now! Only commercial (paid) support is available now to avoid spammy issues. No Mac system is required.

File Explorer

Download Latest Version (.zip)

- FUNDING.yml
- boot-macOS-headless.sh
- config.plist
- create_iso_catalina.sh
- opencore-image-ng.sh
- OpenCore.qcow2
- README.md
- .synergy.conf
- 20120105_202426_apple_sealing.pdf
- idadif.py
- kernel.dif
- kernel_autopatcher.py
- OcBinaryData
- OVMF_VARS.fd
- README.md
- Content-Caching-Works-Screenshot_2023-07-29_20-02-16.png
- ida-patch.png
- macOS+QEMU+AVX.png
- macOS-expose-AVX2.png
- macOS-kernel-patching-1.png
- macOS-kernel-patching-2.png
- macOS-Sierra-KVM.png
- QHM623_USB_Sound_Card_1.jpg
- Screenshot_2023-04-08_10-07-09.png
- Screenshot_2023-04-08_12-33-15.png
- Screenshot_2023-04-08_23-17-52.png
- Sequoia - Screenshot_2024-09-24_12-26-48.png
- unraid-oc-efi.png
- unraid-oc-plist.png
- USB-Sound-Dongle-in-macOS-without-controller-passthrough-2.png
- USB-Sound-Dongle-in-macOS-without-controller-passthrough.png
- Ventura-Resolution-Problem.png
- Ventura_2023-04-08_09-40-45.png
- - Makefile
- - Makefile
- - Makefile
- create_dmg_bigsur.sh
- create_dmg_catalina.sh
- create_dmg_highsierra.sh
- create_dmg_mojave.sh
- create_dmg_monterey.sh
- create_dmg_ventura.sh
- list_iommu_groups.sh
- lsgroup.sh
- run_offline.sh
- vfio-group.sh
- vfio-ungroup.sh
.envrc
.gitignore
.gitmodules
98-sound-dongle.rules
99-usb-disk.rules
boot-linux-for-debugging.sh
boot-macOS-headless.sh
boot-passthrough-windows.sh
boot-passthrough.sh
boot-windows.sh
bridge.conf
CREDITS.md
fetch-macOS-v2.py
flake.lock
flake.nix
kernel-debugging-notes.txt
kvm.conf
kvm_amd.conf
macOS-Cloud.md
macOS-libvirt-Catalina.xml
Makefile
networking-qemu-kvm-howto.txt
notes.md
OpenCore-Boot-CD.sh
OpenCore-Boot-macOS.sh
OpenCore-Boot.sh
OVMF-notes.txt
OVMF_CODE_4M.fd
OVMF_VARS-1024x768.fd
OVMF_VARS-1920x1080.fd
OVMF_VARS.fd
README.md
References.md
reversing-notes.md
run-diagnostics.sh
run_offline.md
UNRAID.md
vfio-kvm.rules
Xcode-Tutorial.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

### 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](mailto:dhiru.kholia@gmail.com?subject=[GitHub]%20OSX-KVM%20Commercial%20Support%20Request&body=Hi%20-%20We%20are%20interested%20in%20purchasing%20commercial%20support%20options%20for%20your%20project.) 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](https://www.nicksherlock.com/)
- Here’s a more up-to-date version for `Proxmox` [OpenCore-ISO](https://github.com/LongQT-sea/OpenCore-ISO)

Yes, we support offline macOS installations now - see [this document](./run_offline.md) 🎉

### 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](https://github.com/munki/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.

```bash
    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](./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](notes.md). We would like to resume our testing and
documentation work around this area. Please [reach out to us](mailto:dhiru.kholia@gmail.com?subject=[GitHub]%20OSX-KVM%20Funding%20Support)
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](networking-qemu-kvm-howto.txt) 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](notes.md#gpu-passthrough-notes).

* Need a different resolution? Check out the [notes](notes.md#change-resolution-in-opencore) included in this repository.

* Trouble with iMessage? Check out the [notes](notes.md#trouble-with-imessage) 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](http://www.rcfp.org/sites/default/files/docs/20120105_202426_apple_sealing.pdf). 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](https://dortania.github.io/OpenCore-Install-Guide/why-oc.html#legality-of-hackintoshing).

Gabriel Somlo also has [some thoughts](http://www.contrib.andrew.cmu.edu/~somlo/OSXKVM/) on the legal aspects involved in running macOS under QEMU/KVM.

You may also find [this 'Announcing Amazon EC2 Mac instances for macOS' article](https://aws.amazon.com/about-aws/whats-new/2020/11/announcing-amazon-ec2-mac-instances-for-macos/
) 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](https://github.com/openwall/john/blob/bleeding-jumbo/src/keychain_fmt_plug.c) a lot harder than it needed to be. This is how I got interested in Hackintosh systems.