{"id":13419534,"url":"https://github.com/kholia/OSX-KVM","last_synced_at":"2025-03-15T05:31:37.252Z","repository":{"id":37333935,"uuid":"45680749","full_name":"kholia/OSX-KVM","owner":"kholia","description":"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.","archived":false,"fork":false,"pushed_at":"2024-10-10T06:13:13.000Z","size":148232,"stargazers_count":20350,"open_issues_count":5,"forks_count":1857,"subscribers_count":495,"default_branch":"master","last_synced_at":"2024-10-14T20:22:46.068Z","etag":null,"topics":["bigsur","bigsur-hackintosh","catalina-hackinotsh","emulation","hackintosh","kernel-debugging","kvm","macos","macos-installer","macos-mojave","monterey","monterey-hackintosh","osx","qemu","qemu-kvm","sonoma-hackintosh","ventura","ventura-hackintosh","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kholia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"kholia"}},"created_at":"2015-11-06T12:27:28.000Z","updated_at":"2024-10-14T18:30:22.000Z","dependencies_parsed_at":"2023-02-06T08:00:42.578Z","dependency_job_id":"214c27af-91ca-494f-8ba8-8275c5ae266b","html_url":"https://github.com/kholia/OSX-KVM","commit_stats":{"total_commits":25,"total_committers":5,"mean_commits":5.0,"dds":"0.31999999999999995","last_synced_commit":"422bb3b7137cd13468aee86de3640835e1d774f9"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kholia%2FOSX-KVM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kholia%2FOSX-KVM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kholia%2FOSX-KVM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kholia%2FOSX-KVM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kholia","download_url":"https://codeload.github.com/kholia/OSX-KVM/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243690111,"owners_count":20331726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bigsur","bigsur-hackintosh","catalina-hackinotsh","emulation","hackintosh","kernel-debugging","kvm","macos","macos-installer","macos-mojave","monterey","monterey-hackintosh","osx","qemu","qemu-kvm","sonoma-hackintosh","ventura","ventura-hackintosh","virtualization"],"created_at":"2024-07-30T22:01:17.334Z","updated_at":"2025-03-15T05:31:37.247Z","avatar_url":"https://github.com/kholia.png","language":"Python","funding_links":["https://github.com/sponsors/kholia"],"categories":["HarmonyOS","Python","Shell","macos","Python (1887)","其他__大数据","macOS","Virtualization"],"sub_categories":["Windows Manager","网络服务_其他","KVM"],"readme":"### Note\n\nThis `README.md` documents the process of creating a `Virtual Hackintosh`\nsystem.\n\nNote: All blobs and resources included in this repository are re-derivable (all\ninstructions are included!).\n\n:green_heart: Looking for **commercial** support with this stuff? I am [available\nover email](mailto:dhiru.kholia@gmail.com?subject=[GitHub]%20OSX-KVM%20Commercial%20Support%20Request\u0026body=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.\n\nStruggling with `Content Caching` stuff? We can help.\n\nWorking with `Proxmox` and macOS? See [Nick's blog for sure](https://www.nicksherlock.com/).\n\nYes, we support offline macOS installations now - see [this document](./run_offline.md) 🎉\n\n\n### Contributing Back\n\nThis project can always use your help, time and attention. I am looking for\nhelp (pull-requests!) with the following work items:\n\n* Documentation around running macOS on popular cloud providers (Hetzner, GCP,\n  AWS). See the `Is This Legal?` section and associated references.\n\n* Document (share) how you use this project to build + test open-source\n  projects / get your stuff done.\n\n* Document how to use this project for XNU kernel debugging and development.\n\n* Document the process to launch a bunch of headless macOS VMs (build farm).\n\n* Document usage of [munki](https://github.com/munki/munki) to deploy software\n  to such a `build farm`.\n\n* Enable VNC + SSH support out of the box or more easily.\n\n* Robustness improvements are always welcome!\n\n* (Not so) crazy idea - automate the macOS installation via OpenCV.\n\n\n### Requirements\n\n* A modern Linux distribution. E.g. Ubuntu 24.04 LTS 64-bit or later.\n\n* QEMU \u003e= 8.2.2\n\n* A CPU with Intel VT-x / AMD SVM support is required (`grep -e vmx -e svm /proc/cpuinfo`)\n\n* A CPU with SSE4.1 support is required for \u003e= macOS Sierra\n\n* A CPU with AVX2 support is required for \u003e= macOS Ventura\n\nNote: Older AMD CPU(s) are known to be problematic but modern AMD Ryzen\nprocessors work just fine (even for macOS Sonoma).\n\n\n### Installation Preparation\n\n* Install QEMU and other packages.\n\n  ```\n  sudo apt-get install qemu-system uml-utilities virt-manager git \\\n      wget libguestfs-tools p7zip-full make dmg2img tesseract-ocr \\\n      tesseract-ocr-eng genisoimage vim net-tools screen -y\n  ```\n\n  This step may need to be adapted for your Linux distribution.\n\n* Clone this repository on your QEMU system. Files from this repository are\n  used in the following steps.\n\n  ```\n  cd ~\n\n  git clone --depth 1 --recursive https://github.com/kholia/OSX-KVM.git\n\n  cd OSX-KVM\n  ```\n\n  Repository updates can be pulled via the following command:\n\n  ```\n  git pull --rebase\n  ```\n\n  This repository uses rebase based workflows heavily.\n\n* KVM may need the following tweak on the host machine to work.\n\n  ```\n  sudo modprobe kvm; echo 1 | sudo tee /sys/module/kvm/parameters/ignore_msrs\n  ```\n\n  To make this change permanent, you may use the following command.\n\n  ```\n  sudo cp kvm.conf /etc/modprobe.d/kvm.conf  # for intel boxes only\n\n  sudo cp kvm_amd.conf /etc/modprobe.d/kvm.conf  # for amd boxes only\n  ```\n\n* Add user to the `kvm` and `libvirt` groups (might be needed).\n\n  ```\n  sudo usermod -aG kvm $(whoami)\n  sudo usermod -aG libvirt $(whoami)\n  sudo usermod -aG input $(whoami)\n  ```\n\n  Note: Re-login after executing this command.\n\n* Fetch macOS installer.\n\n  ```\n  ./fetch-macOS-v2.py\n  ```\n\n  You can choose your desired macOS version here. After executing this step,\n  you should have the `BaseSystem.dmg` file in the current folder.\n\n  ATTENTION: Let `\u003e= Big Sur` setup sit at the `Country Selection` screen, and\n  other similar places for a while if things are being slow. The initial macOS\n  setup wizard will eventually succeed.\n\n  Sample run:\n\n  ```\n  $ ./fetch-macOS-v2.py\n  1. High Sierra (10.13)\n  2. Mojave (10.14)\n  3. Catalina (10.15)\n  4. Big Sur (11.7)\n  5. Monterey (12.6)\n  6. Ventura (13) - RECOMMENDED\n  7. Sonoma (14)\n  8. Sequoia (15)\n\n  Choose a product to download (1-8): 6\n  ```\n\n  Note: Modern NVIDIA GPUs are supported on HighSierra but not on later\n  versions of macOS.\n\n* Convert the downloaded `BaseSystem.dmg` file into the `BaseSystem.img` file.\n\n  ```\n  dmg2img -i BaseSystem.dmg BaseSystem.img\n  ```\n\n* Create a virtual HDD image where macOS will be installed. If you change the\n  name of the disk image from `mac_hdd_ng.img` to something else, the boot scripts\n  will need to be updated to point to the new image name.\n\n  ```\n  qemu-img create -f qcow2 mac_hdd_ng.img 256G\n  ```\n\n  NOTE: Create this HDD image file on a fast SSD/NVMe disk for best results.\n\n* Now you are ready to install macOS 🚀\n\n\n### Installation\n\n- CLI method (primary). Just run the `OpenCore-Boot.sh` script to start the\n  installation process.\n\n  ```\n  ./OpenCore-Boot.sh\n  ```\n\n  Note: This same script works for all recent macOS versions.\n\n- Use the `Disk Utility` tool within the macOS installer to partition, and\n  format the virtual disk attached to the macOS VM. Use `APFS` (the default)\n  for modern macOS versions.\n\n- Go ahead, and install macOS 🙌\n\n- (OPTIONAL) Use this macOS VM disk with libvirt (virt-manager / virsh stuff).\n\n  - Edit `macOS-libvirt-Catalina.xml` file and change the various file paths (search\n    for `CHANGEME` strings in that file). The following command should do the\n    trick usually.\n\n    ```\n    sed \"s/CHANGEME/$USER/g\" macOS-libvirt-Catalina.xml \u003e macOS.xml\n\n    virt-xml-validate macOS.xml\n    ```\n\n  - Create a VM by running the following command.\n\n    ```bash\n    virsh --connect qemu:///system define macOS.xml\n    ```\n\n  - If needed, grant necessary permissions to libvirt-qemu user,\n\n    ```\n    sudo setfacl -m u:libvirt-qemu:rx /home/$USER\n    sudo setfacl -R -m u:libvirt-qemu:rx /home/$USER/OSX-KVM\n    ```\n\n  - Launch `virt-manager` and start the `macOS` virtual machine.\n\n\n### Headless macOS\n\n- Use the provided [boot-macOS-headless.sh](./boot-macOS-headless.sh) script.\n\n  ```\n  ./boot-macOS-headless.sh\n  ```\n\n\n### Setting Expectations Right\n\nNice job on setting up a `Virtual Hackintosh` system! Such a system can be used\nfor a variety of purposes (e.g. software builds, testing, reversing work), and\nit may be all you need, along with some tweaks documented in this repository.\n\nHowever, such a system lacks graphical acceleration, a reliable sound sub-system,\nUSB 3 functionality and other similar things. To enable these things, take a\nlook at our [notes](notes.md). We would like to resume our testing and\ndocumentation work around this area. Please [reach out to us](mailto:dhiru.kholia@gmail.com?subject=[GitHub]%20OSX-KVM%20Funding%20Support)\nif you are able to fund this area of work.\n\nIt is possible to have 'beyond-native-apple-hw' performance but it does require\nwork, patience, and a bit of luck (perhaps?).\n\n\n### Post-Installation\n\n* 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.\n\n* To passthrough GPUs and other devices, see [these notes](notes.md#gpu-passthrough-notes).\n\n* Need a different resolution? Check out the [notes](notes.md#change-resolution-in-opencore) included in this repository.\n\n* Trouble with iMessage? Check out the [notes](notes.md#trouble-with-imessage) included in this repository.\n\n* Highly recommended macOS tweaks - https://github.com/sickcodes/osx-optimizer\n\n\n### Is This Legal?\n\nThe \"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.\n\nPlease 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).\n\nGabriel Somlo also has [some thoughts](http://www.contrib.andrew.cmu.edu/~somlo/OSXKVM/) on the legal aspects involved in running macOS under QEMU/KVM.\n\nYou 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/\n) interesting.\n\nNote: It is your responsibility to understand, and accept (or not accept) the\nApple EULA.\n\nNote: This is not legal advice, so please make the proper assessments yourself\nand discuss with your lawyers if you have any concerns (Text credit: Dortania)\n\n\n### Motivation\n\nMy aim is to enable macOS based educational tasks, builds + testing, kernel\ndebugging, reversing, and macOS security research in an easy, reproducible\nmanner without getting 'invested' in Apple's closed ecosystem (too heavily).\n\nThese `Virtual Hackintosh` systems are not intended to replace the genuine\nphysical macOS systems.\n\nPersonally speaking, this repository has been a way for me to 'exit' the Apple\necosystem. It has helped me to test and compare the interoperability of `Canon\nCanoScan LiDE 120` scanner, and `Brother HL-2250DN` laser printer. And these\ndevices now work decently enough on modern versions of Ubuntu (Yay for free\nsoftware). Also, a long time back, I had to completely wipe my (then) brand new\n`MacBook Pro (Retina, 15-inch, Late 2013)` and install Xubuntu on it - as the\n`OS X` kernel kept crashing on it!\n\nBackstory: 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkholia%2FOSX-KVM","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkholia%2FOSX-KVM","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkholia%2FOSX-KVM/lists"}