PECU turns Proxmox host configuration into a menu with a rollback path

A menu for the steps you keep repeating

PECU is a Bash utility for Proxmox VE whose stated focus is repeatable host configuration and GPU passthrough workflows. The design centre is an interactive, menu-driven interface covering repositories, kernel parameters, VFIO, rollback and templates, and the README names the qualities it tries to hold onto: safe reruns in the sense of idempotency, backups, and clear logging. That combination is the reason a homelab administrator would reach for a script at all. A Proxmox host that passes a GPU through to a virtual machine needs a specific set of things right, and those things differ between an AMD and an Intel board, between a GRUB and a systemd-boot machine, and between a fresh install and one that has already been configured once. The primary use cases listed are GPU passthrough setup and verification for NVIDIA, AMD and Intel, bootloader-aware kernel parameter management, VFIO configuration with validation and rollback support, and VM template creation through a declarative template system. Verification is called out separately from setup, which suggests the tool expects to be run again after a reboot to confirm the result.

VFIO with validation and a way back

The passthrough work is where a mistake costs the most, and PECU treats that part as the serious one. VFIO configuration is described as coming with validation and rollback support, which are two features that most passthrough scripts omit. Validation in this context means checking the configuration rather than assuming the machine will come up, and rollback means having a path back to a bootable state. The mechanism behind both is the same set of underlying mechanisms the script touches: boot parameters, the initramfs and modprobe configuration. A passthrough setup that binds a GPU to vfio-pci usually needs a module configuration change so the driver does not claim the device, and a kernel parameter change so the IOMMU is enabled, and the initramfs has to be rebuilt so the early userspace picks up the new module configuration. If any one of those three goes wrong, the host may not boot into a usable desktop, which is exactly why the console requirement in the documentation is not a formality.

Kernel parameters without guessing the bootloader

The bootloader-aware part is what separates this from a script that appends a line to a config file. The same kernel parameter has to be written in a different place and a different form depending on whether the machine boots through systemd-boot or GRUB, and a script that guesses wrong will either do nothing or produce a bootloader that refuses to start. PECU handles both, which means the same script can be pointed at a heterogeneous set of hosts, which is the normal situation in a homelab where machines were assembled at different times. The parameters being managed are the ones that matter for device passthrough, in particular the IOMMU enablement needed for VFIO, and the modprobe side handles the driver binding. The interactive menu is what makes this navigable, because the order matters. You want the module configuration in place before the initramfs is rebuilt, and you want the parameters written before the machine reboots, and a script that exposes the steps as menu entries lets an operator follow the right order without reading the source first.

Pin a release tag instead of tracking main

The quick start has three routes, and the middle one exists for a reason. The recommended one pipes a release selector script straight into bash, and that script fetches the available tagged releases and lets you pick a version or channel:

bash <(curl -fsSL https://raw.githubusercontent.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/main/scripts/pecu_release_selector.sh)

The problem with that is that it resolves to whatever main happens to be at the moment you run it, which is the wrong property for a script that edits boot configuration. The second route pins a tag, and the README recommends it for reproducibility in documentation and automation:

TAG="v2026.01.05"
bash <(curl -fsSL "https://raw.githubusercontent.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/${TAG}/src/proxmox-configurator.sh")

The entry point for a pinned run is src/proxmox-configurator.sh, and the release bundles are published under the same naming scheme. For an air-gapped or reproducible environment there is a third route, since every release ships a tar.gz bundle. The download and verification steps are:

VERSION="v2026.01.05"  # choose a tag from the Releases page
wget "https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/releases/download/${VERSION}/PECU-${VERSION#v}.tar.gz"
wget "https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/releases/download/${VERSION}/SHA256SUMS"
sha256sum -c SHA256SUMS
tar -xzf "PECU-${VERSION#v}.tar.gz"
cd "PECU-${VERSION#v}"

The SHA256SUMS file is published next to the bundle, so the offline path is the only one that verifies what it downloaded, and it is the path to prefer when the script is going to be run unattended.

Bundle layouts vary, so entry point detection is explicit

One detail in the offline instructions is easy to skim past and worth reading. After extraction, the script does not assume a fixed layout, because bundle layouts may differ between releases. The entry point is found by testing for the two known locations and failing loudly if neither exists:

if [ -x "src/proxmox-configurator.sh" ]; then
  chmod +x src/proxmox-configurator.sh
  sudo ./src/proxmox-configurator.sh
elif [ -x "proxmox-configurator.sh" ]; then
  chmod +x proxmox-configurator.sh
  sudo ./proxmox-configurator.sh
else
  echo "Could not find proxmox-configurator.sh in the extracted bundle."
  echo "Expected: ./src/proxmox-configurator.sh or ./proxmox-configurator.sh"
  exit 1
fi

Two things are worth noting. The script is run under sudo, which matches the stated requirement of root or sudo, and the failure path prints the paths it expected rather than failing silently, so a bundle that has been restructured does not leave you guessing. The chmod before execution is also not cosmetic, because a tarball extracted from an archive does not necessarily preserve the executable bit the way you would want. The repository layout supports the same picture at the top level, with a scripts/ directory holding the release selector, a src/ directory holding the main script, a templates/ directory for the template system, doc/ for images and documentation, plus a wiki as the documentation site.

The template system adds a Python toolchain

The newer part of PECU is the VM template system, which is described as declarative and as a template system of its own. It comes with its own requirements, and they are specific: python3, PyYAML and jsonschema for local validation. That combination tells you the shape of it, since YAML is the likely input format for a human-written template, jsonschema is what validates that YAML against a declared structure, and the validation is explicitly local, meaning it happens on the machine where you edit the template rather than on the Proxmox host. A real Proxmox host is needed only for a non-dry-run apply, which means the authoring loop is fast and can be exercised in CI or on a laptop. The dry run distinction is the important operational detail here, because a template that applies cleanly to a test host and then fails on a real host is a template problem,. The release notes file in the repository is named for experimental work, and the latest release is titled Template System Hardening, which is a good description of where the effort is going.

The boundaries are explicit and worth respecting

The requirements table is honest about what PECU will not do. The platform is Proxmox VE 7, 8 or 9, the CPU architecture must be x86-64, the bootloader must be GRUB or systemd-boot, and root or sudo is required. ARM and Raspberry Pi builds of Proxmox are explicitly not supported at this time, which follows from the x86-64 requirement and the vfio-pci path being used. The documentation also states plainly that the project modifies system configuration in the form of boot params, initramfs and modprobe, and that you should review the changes and make sure you have console access before applying them. That warning is the single most important line in the README for an evaluation. A script that can leave a host unbootable needs either a verified backup or a physical console, and the project is candid that this is on you. The licence is GPL-3.0, the project links a wiki for documentation, and the repository also ships a pre-commit configuration and a yamllint configuration, which is consistent with the declarative template files being linted before they reach a host.

Editorial conclusion

PECU fits a homelab or small cluster administrator who repeatedly rebuilds Proxmox hosts and wants the passthrough and VFIO steps written down as an idempotent script rather than a wiki page of copy and paste commands, and the pinned release tarballs with SHA256SUMS are what make that safe to hand to somebody else. It does not fit an ARM or Raspberry Pi Proxmox installation, and it does not fit anyone who cannot reach the host console, because the project says outright that it modifies boot parameters, initramfs and modprobe configuration. Before running it, take a console session, read the diff it proposes, and check the template tooling dependencies, since the declarative path needs python3, PyYAML and jsonschema and only needs a real Proxmox host for a non-dry-run apply. The last push was on 2026-05-17 and the newest release, v2026.05.11, is dated 2026-05-11.

Frequently asked questions

Official sources

1. Danilop95/Proxmox-Enhanced-Configuration-Utility on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases