ultimate-macOS-KVM: A Python repository from rahulmr

v0.9.8

Helping you build the ultimate macOS virtual machine, powered by KVM.

Introduction

Tired of all the restraints and poor performance of macOS VMs in hypervisors like VirtualBox or VMware? Well, the story changes when you run your virtual machines in kernel space. Welcome to the world of Kernel Virtual Machines.

You might be new to QEMU/KVM, or a long-time veteran - either way this project aims to help you build a macOS virtual machine that can take full advantage of the power of KVM - but in a user-friendly and approachable way.

Scripts? Configs? QEMU arguments? A "qcow" file? Moo? If you need a little help wrapping your head around this stuff, feel free to check out the FAQs for some quick knowledge on the basics.

Requirements

As with all other virtual machines / hypervisors, you don't need an uber-powerful PC, but you should expect guest performance to be relative to your host's. Performance can change dramatically based on guest properties, such as virtual cores, allocated memory, and virtual CPU threads - but it really does boil down to how beefy your host's hardware is. Here's a table with my best judgement on minimum, recommended, and best system requirements:

	Minimum	Recommended	Optimal	My Setup
OS	linux-5.x	Linux Mint	Arch Linux	Arch Linux
Motherboard	Virtualisation UEFI	Virtualisation UEFI IOMMU Intel VT-d / AMD-V	Virtualisation UEFI IOMMU Intel VT-d / AMD-V Isolated PCI Lanes	ROG STRIX Z490-E GAMING UEFI IOMMU Intel VT-d Isolated PCI lanes
CPU	~2014 Intel / AMD Virtualisation 2 cores	Intel i5 / Ryzen 5 Virtualisation 4-8 cores Hyperthreaded	Intel i9 / Ryzen 9 Virtualisation 8-16 cores Hyperthreaded	Intel Core i9-10900K 10 cores Hyperthreaded
Memory	4 GB	16 GB	32 GB+	64 GB
Disk Type	SATA HDD	SATA SSD	NVMe SSD	NVMe SSD
Disk Space	40 GB	120 GB	500 GB+	500 GB
Resolution	1280x720	2560x1440	3840x2160	2560x1440
GPU (VFIO)	-	AMD RX 580	AMD RX 6600 XT	AMD RX 550

Dependencies

You must also have all the required dependencies installed before starting.

Optional dependencies can enhance your experience, such as using your VM in a GUI, or showing what macOS version you're currently running on your Discord profile.

Required

Git 》 git
Wget 》 wget
QEMU 》 qemu-base or qemu-full
Libvirt 》 libvirt
DNSmasq 》 dnsmasq
Python 》 python

Optional / Recommended

Virtual Machine Manager (GUI) 》 virt-manager
Virsh 》 virsh
Discord Rich Presence (pypresence) 》 python-pypresence or, using pip, install pypresence

Oh, and you NEED Linux

Shocker; KVM is a module built into the Linux kernel. Not Windows Subsystem for Linux or some UNIX-like terminal. You need a full install of at least base Linux on your host. Don't try any of that VM inception shenanigans.

The easiest way to do this is by grabbing some mainstream Linux distro, like Ubuntu, Linux Mint, Manjaro, endeavourOS - among many, many others. You can pick any one you like. If it's Linux - you can use this project. I use Arch BTW.

Features

AutoPilot
Automatic System Checks
GPU Compatibility Checker
VFIO-IDs and IOMMU Helpers
VFIO-PCI Passthrough Assistant
Import to virt-manager

Getting Started

It's easy to get up and running. Simply clone the repo, fix permissions, and run. Make sure you have all dependencies installed before getting started.

$ git clone https://github.com/Coopydood/ultimate-macOS-KVM
$ cd ultimate-macOS-KVM
$ chmod +x main.py

or, do all this with a one-liner:

$ git clone https://github.com/Coopydood/ultimate-macOS-KVM && cd ultimate-macOS-KVM && chmod +x main.py

Alternatively, you can download the latest release here: Download

Setup

Okay, so you've cloned my repo, cd'd into the directory, and made the main.py file executeable. Great! Now, before running the script - and to avoid the subsequent and inevitable gotcha - you should enable the libvirtd daemon first if it hasn't been already:

$ sudo systemctl enable libvirtd

and/or check the status of the daemon with

$ systemctl status libvirtd

Okay, now you're ready to use ultimate-macOS-KVM. Use the main.py file.

This is your main menu / central hub for the project and everything can be accessed from here. Most sub-scripts included in the project should not be run on their own.

$ ./main.py

I'm here for GPU passthrough

...and you've come to the right place. ultimate-macOS-KVM includes several handy built-in tools to make VFIO-PCI passthrough (including GPUs) as painfree as possible. Please see the documentation on how to get started with these tools.

Oh, and speaking of...

Documentation

More detailed write-ups on the project and the scripts included, as well as some tutorials can be found on this repo's wiki.

Or, you can find some in the included docs folder.

Updates

This project has been designed to be updated and made better over time.

As you use it to generate your personal files, having to re-clone the entire repo yourself while preserving your files would be a right pain in the backside. Therefore, there's an automated updater script built right-in that you can use to safely update in-place to newer versions of this project, without affecting any of your personal config files, virtual hard drives, or anything else not part of the project files. And, if an update dramatically changes directory structures from your current version, the updater automatically disables its in-place update mechanism to prevent data loss.

Of course, if you're just testing the project, then a "clean install" is probably still preferable.

Disclaimer

This is my way of giving back to the QEMU, KVM, and VFIO community. Please don't expect much as this is a passion-project and not a priority in my life.

I'm not responsible for any time you waste using this project.
I'm not responsible if you make an oopsie whoopsie.
Do NOT run anything as sudo. If you have an urge to then you need to break that habit asap. None of my scripts require superuser privileges.
Expect headaches. Some severe.
You need a LOT of patience. I mean it. Despite me trying to alleviate some of the hassle, you WILL run into stupid gotchas that require trial and error out of my control.
I'm by no means an expert on this stuff nor would I claim to be.
I've simply made what I had to go through easier for you. Hopefully.
Yes, my Python is pretty bad. But if it works, it works.

Credits & Greetz

While I am the creator of these automation/ease-of-use scripts, this project is not possible without both the prior and current works of some very talented people. The people who have tested the project are also included.

Dortania 》 Extensive documentation and Hackintosh development.
Kholia 》 Development of scripts and documentation. ultimate-macOS-KVM is intended as an extension to OSX-KVM.
thenickdude 》 Personal support throughout my KVM misadventures and countless community contribs. Cheers.
vu1tur 》 Open source dmg to img conversion tool; used and bundled by this project.
Eversiege 》 Support and testing, та мій улюблений українець.
CyberneticSquid 》 Testing for me at stupid-o'-clock because he's a cool Aussie.
Cake 》 Another Aussie testing for me in the middle of my sleep-deprived nights, with a slight obsession over cake.
DomTrues 》 My personal constitution-munching American. Legend has it that I live in his attic, although even I'm not sure. Love this guy either way.
Kaz 》 Other than his brilliant English accent's pronounciations (including "macOS Syria"), he's done extensive testing. Say hi to your nephew for me.
GigantTech 》 Moderately annoying German guy that I convinced to install Linux subsequently letting him test my project. It's free real estate!

rahulmr/ultimate-macOS-KVM