base on 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. ### 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:[email protected]?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/). 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. ``` 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) - RECOMMENDED 7. Sonoma (14) 8. Sequoia (15) Choose a product to download (1-8): 6 ``` 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:[email protected]?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. ", Assign "at most 3 tags" to the expected json: {"id":"1675","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"