OSX-PROXMOX: Installing macOS on Proxmox VE with a One-Line Script

What OSX-PROXMOX actually automates

Installing macOS on Proxmox VE by hand means assembling an OpenCore EFI, picking SMBIOS values, building a recovery image, and wiring the VM configuration so the guest boots. OSX-PROXMOX packages that work into a Shell installer aimed at people who already have Proxmox VE running but do not want to hand-build the boot chain. The README frames the audience plainly: it is for AMD and Intel hosts, and the disclaimer restricts it to development, student and testing purposes. That framing matters. This is not a path to a supported Apple system, and the project says so before the install steps. The repository ships an install.sh, an EFI directory, Patches, tools and setup folders, so the installer is not a single opaque binary: the pieces it deploys are visible in the tree. The project is not archived, and the last push was on 2026-09-07.

The mechanism: a fresh PVE host, OpenCore, and a VM

The installer assumes a clean Proxmox VE installation in the 7.XX to 9.XX range and then provisions the macOS boot environment on top of it. The bootloader is OpenCore, credited to the Acidanthera team, and the README pins the version it ships: March/2026, 1.0.7, with SIP enabled and DMGs signed only by Apple. That detail is the project's security posture in one line: system integrity protection stays on, and the guest refuses unsigned disk images. Guest support runs from macOS High Sierra 10.13 through macOS Tahoe 26. The repository layout suggests how the installer is organised. EFI holds the boot payload, Patches holds the per-version or per-hardware adjustments, tools holds helper utilities, and setup holds the configuration the script applies to Proxmox. The README also notes configurable bridges, and that you can add as many bridges as you want and specify the subnet for each, which is the networking surface the installer exposes. The project's own homepage is osx-proxmox.com, and the install script is fetched from install.osx-proxmox.com, so the runtime depends on that host being reachable at install time.

Installing OSX-PROXMOX and booting a first macOS VM

Start from a fresh Proxmox VE installation. The README is explicit that it should be clean, and that the supported range is v7.XX.XX to 9.XX.XX. Then open the Proxmox web console, go to Datacenter, then your host name, then Shell, and run the installer:

/bin/bash -c "$(curl -fsSL https://install.osx-proxmox.com)"

The README says a particular screen after the install is normal, and shows it as a screenshot rather than describing it in text, so expect an output that looks alarming but is documented as expected. Once the installer finishes, the README's claim is simply that you can now install macOS.

Inside the guest, if you need to install the EFI package, the README's additional configuration step is to disable Gatekeeper first:

sudo spctl --master-disable

Before any of this, check the host clock source, because the README ties multi-core stability to it:

dmesg | grep -i -e tsc -e clocksource

A working host shows `clocksource: Switched to clocksource tsc`. A broken one shows a TSC instability message and falls back to hpet. You can confirm the active source directly:

cat /sys/devices/system/clocksource/clocksource0/current_clocksource

The README states the output must be `tsc`.

The TSC requirement is the real gate

Since macOS Monterey, the README states that the host needs a working timestamp counter, and that if you assign multiple cores to the VM without one, macOS may crash from time inconsistencies. This is the sharpest limitation in the project, because it is a host hardware and firmware property that no installer can repair. The documented workarounds are BIOS-level: disable ErP mode and all C-state power-saving modes, power the machine off completely, and restart. If that fails, the README offers forcing TSC in GRUB by editing /etc/default/grub and appending `clocksource=tsc tsc=reliable`, then running update-grub and rebooting. It flags that this may cause instability. Read that as a warning, not a formality: you are telling the kernel to trust a counter the firmware already reported as unreliable. A single-core VM may dodge the crash, but the README does not present that as a supported configuration, and assigning one core to a macOS guest is rarely what anyone wants. Check TSC before you install, not after the first kernel panic.

GPU passthrough is documented, but it is manual work

The README treats passthrough as a troubleshooting topic rather than part of the installer. If you see an Apple logo with a progress bar that does not move on an external display, the documented fix is to disable above 4G decoding in the motherboard BIOS. Beyond that, the README describes segmenting IOMMU groups so a GPU can be handed to the VM. The steps are edits to /etc/default/grub, appending `pcie_acs_override=downstream,multifunction pci=nommconf` to GRUB_CMDLINE_LINUX_DEFAULT, and in some environments also `pcie_port_pm=off`. After editing, you run update-grub and reboot Proxmox VE. Some environments also need a /etc/modprobe.d/vfio-pci.conf containing `options vfio-pci ids=XXXX:XXXX,XXXX:XXXX disable_vga=on`. Note what the README does not provide: it does not give you the IOMMU group layout for your board, it does not pick the ids for you, and it does not confirm that passthrough will work on your combination of CPU, chipset and GPU. The installer gets macOS booting; making a real GPU appear inside it is a separate project with its own failure modes.

High Sierra recovery and the HTTPS to HTTP workaround

Older macOS versions fail in a way the README documents in detail. On High Sierra and below, the installer can report that the recovery server could not be contacted. The documented procedure is to leave the error window open, open Installer Log from the Window menu, find the entry about failing to load the catalog, copy it, then close the error and return to macOS Utilities. In Terminal you paste the copied data, strip everything except the URL, change `https://` to `http://`, and set it with:

nvram IASUCatalogURL="http://your-http-url.sucatalog"

Then quit Terminal and restart the installation. The README links to mrmacintosh.com for the underlying explanation. Two things are worth stating plainly. First, this drops the catalog fetch to plain HTTP, which is exactly the kind of change you should understand before making it. Second, the README does not document a rollback for that nvram variable, so if you want to undo it you are working from general macOS knowledge rather than from this project's instructions.

Alternatives and where OSX-PROXMOX sits

The obvious alternative is doing it by hand: install Proxmox VE, then build the OpenCore EFI yourself and configure the VM, following a written guide such as the Nick Sherlock article the README links to in the TSC section. The difference is control versus effort. A manual build lets you choose OpenCore version, SMBIOS values and every kernel flag, and you understand each piece because you assembled it. OSX-PROXMOX trades that for a single command and a maintained EFI directory. The second alternative is not a Proxmox alternative at all: buy or use real Apple hardware, or rent a Mac. That removes the TSC problem, the passthrough problem and the unsupported-guest problem in one move, at the cost of the machine you already own. OSX-PROXMOX only makes sense when the Proxmox host is a given and the macOS guest is the thing you want on it. If the host is not a given, the script is solving a problem you chose to have.

Maintenance, licence and what to verify

The repository is not archived, and the last push was on 2026-09-07, so the project is being touched. Releases are not listed in the retrieved material, which means upgrade tracking leans on the CHANGELOG.md file in the repository root rather than on tagged releases. That is a real cost: without releases you cannot pin a version number in the usual way, and you should read the changelog before re-running the installer on a host that already works. The installer fetches from install.osx-proxmox.com at run time, so an upgrade is also a network dependency. On licensing, the repository's license field is unknown and the README's badge points at a license file that the retrieved material does not resolve. That is worth checking yourself before any redistribution or commercial use, because OpenCore, the macOS installer images and the project's own Shell code are three separate licensing questions. The README's disclaimer limits the project to development, student and testing purposes, and states the author is not responsible for damage or data loss. Treat that as the boundary it is, not as boilerplate.

Editorial conclusion

Adopt OSX-PROXMOX if you already run Proxmox VE on a spare Intel or AMD machine and want a macOS VM for development or testing without assembling an OpenCore config by hand. Do not adopt it if your host has unstable TSC, if you need a supported Apple platform, or if you expect the installer to handle GPU passthrough for you: the README leaves that to manual GRUB and vfio-pci edits. Before installing, run dmesg | grep -i -e tsc -e clocksource and confirm the current clock source reads tsc, because that single check decides whether a multi-core macOS VM will stay stable.

Frequently asked questions

Official sources

1. Issues
2. luchina-gabriel/OSX-PROXMOX on GitHub
3. Project website
4. README