Provisioning macOS virtual machines on Proxmox VE has historically been a manual, time-consuming task with many pitfalls. osx-proxmox-next tackles this by providing a Python-based terminal UI wizard that collapses a multi-hour setup into a guided 6-step workflow or a single command for headless automation. This approach lowers the barrier for running macOS VMs on Proxmox 9, making the process more approachable and less error-prone.
What osx-proxmox-next does and how it works
osx-proxmox-next is a Python tool designed specifically for automating macOS VM provisioning on Proxmox 9 hosts. It offers an interactive TUI (terminal user interface) wizard that walks you through VM creation or a headless CLI mode suitable for script integration.
The tool handles several key tasks:
CPU vendor auto-detection: It detects whether the host CPU is Intel, AMD, Xeon, or an older pre-Skylake model, then automatically applies the appropriate QEMU VM configuration. For example, it uses host passthrough mode on modern Intel CPUs, Cascadelake-Server emulation for AMD, or Penryn mode for older chips, without requiring manual user input.
OpenCore bootloader and recovery image management: The tool downloads and caches OpenCore bootloader files and macOS recovery images for supported macOS versions (Ventura, Sonoma, Sequoia, Tahoe). This caching dramatically speeds up subsequent VM creations.
SMBIOS identity generation: For each macOS version, the tool generates a suitable SMBIOS profile to improve compatibility and ensure Apple services work properly.
VM creation and configuration: It leverages Proxmox’s
qmcommand-line interface to create and configure the VM, including selecting storage pools, assigning VMIDs, and setting CPU, memory, and disk parameters.
The interactive TUI guides users through six steps: preflight checks and CPU detection, OS version selection, storage pool selection, VM configuration review/editing, a dry run showing all generated commands, and finally installation and VM startup.
A notable feature is the ability to set a shared ISO directory (--iso-dir), enabling asset caching across multiple Proxmox nodes in a cluster, which is practical for larger setups.
The repository also includes a standalone Bash script alternative for users who prefer to avoid Python dependencies. This script replicates the core VM creation logic and uses whiptail menus for interaction.
What makes osx-proxmox-next technically interesting
The standout technical aspect is the intelligent CPU detection and VM configuration logic. macOS virtualization on non-Apple hardware requires careful tuning of the QEMU CPU model and features to avoid kernel panics, boot failures, or degraded performance. This tool encapsulates years of community knowledge about which configurations work best on various CPU architectures.
The codebase is Python-based, organized around a TUI framework that balances user interaction with automation. The developer has streamlined the workflow to avoid unnecessary configuration overhead, improving the developer experience (DX) significantly compared to manual qm commands.
Caching is another practical strength. Downloading OpenCore and recovery images can take time and bandwidth, so the tool caches these assets locally and supports shared storage caching across nodes. This optimization matters in production or multi-VM scenarios.
One of the more unique features is a kernel-level patch related to Apple Services on macOS versions Sequoia and Tahoe. While the analysis only mentions this patch briefly without technical details, it appears to address Apple’s VM detection mechanisms to enable Apple ID sign-in and related services inside the VM. This is a tricky area due to Apple’s hardware checks, and the patch suggests some low-level modification to the guest kernel or QEMU environment. Without explicit code or documentation, it’s best to consider this a valuable but advanced feature.
Tradeoffs include the reliance on Proxmox 9 and the specific QEMU configurations tailored to known CPU microarchitectures. Users with exotic or unsupported CPUs may encounter issues. The automation focuses on macOS VM provisioning only, so users seeking broader virtualization management will need complementary tools.
The Bash alternative script is a nice touch for minimal environments but lacks the polish and flexibility of the Python TUI.
Quick start
The repository provides a straightforward quick start for Proxmox 9 hosts. As root on your Proxmox node, run:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/lucid-fabrics/osx-proxmox-next/main/install.sh)"
This command clones the repo, sets up a Python virtual environment, and launches the interactive TUI wizard.
If you prefer a no-Python dependency approach, you can run the standalone Bash script:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/lucid-fabrics/osx-proxmox-next/main/scripts/bash/osx-proxmox-next.sh)"
The wizard then guides you through the steps:
- Preflight checks and CPU detection.
- Choosing the macOS version.
- Selecting storage.
- Reviewing and editing VM settings.
- Dry run showing all commands.
- Installation and VM startup.
Most users will find the defaults sensible and only need to pick the macOS version and storage before installing.
verdict
osx-proxmox-next is a practical tool for anyone running macOS VMs on Proxmox 9, especially homelab enthusiasts and IT admins who want to save hours of manual setup. Its CPU auto-detection and caching features solve real pain points in macOS virtualization.
While the kernel patch for Apple Services hints at deeper technical sophistication, the lack of detailed public documentation means users should approach this feature as a black box that works rather than something to modify or extend easily.
The Python TUI balances automation and user control nicely, and the Bash alternative broadens accessibility.
Limitations include hardware compatibility constraints and a focus solely on macOS VM provisioning. Still, for its niche, it significantly improves DX and reliability.
If you manage multiple Proxmox nodes or frequently create macOS VMs, this tool can save you significant time and hassle without requiring deep QEMU or Proxmox expertise.
→ GitHub Repo: lucid-fabrics/osx-proxmox-next ⭐ 147 · Python