https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility
Is a comprehensive and versatile Bash script designed to simplify and optimize the configuration and management of Proxmox Virtual Environment (VE) systems.
https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility
automation-scripts debian gpu-passthrough homelab-automation kmu pecu proxmox-ve sysadmin-scripts tools
Last synced: about 2 months ago
JSON representation
Is a comprehensive and versatile Bash script designed to simplify and optimize the configuration and management of Proxmox Virtual Environment (VE) systems.
- Host: GitHub
- URL: https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility
- Owner: Danilop95
- License: gpl-3.0
- Created: 2023-07-08T17:02:01.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-04T16:32:27.000Z (3 months ago)
- Last Synced: 2025-08-04T18:27:40.046Z (3 months ago)
- Topics: automation-scripts, debian, gpu-passthrough, homelab-automation, kmu, pecu, proxmox-ve, sysadmin-scripts, tools
- Language: Shell
- Homepage: http://pecu.tools/
- Size: 873 KB
- Stars: 415
- Watchers: 10
- Forks: 27
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-proxmox-ve - ⚙️ PECU - Configuration utility (🛠️ Tools & Utilities / 🛠️ Utility Scripts & Extensions)
README
Proxmox Enhanced Configuration Utility
( PECU )
## Table of Contents
- [Overview](#overview)
- [Requirements & Compatibility](#requirements--compatibility)
- [Quick Start](#quick-start)
- [Direct execution (recommended)](#direct-execution-recommended)
- [Offline / local install](#offline--local-install)
- [What Is the Release Selector?](#what-is-the-release-selector)
- [VM Templates System](#vm-templates-system)
- [Features](#features)
- [Community & Contribution](#community--contribution)
- [Support the Project](#support-the-project)
- [License](#license)
---
## Overview
**PECU** is a single-shell utility that makes day-to-day Proxmox VE management
as painless as possible:
* one-line installer
* interactive menus for repositories, kernel flags, GPU passthrough, etc.
* reversible operations (backup / rollback built-in)
* auto-detects NVIDIA, AMD **and** Intel iGPUs out of the box
* **NEW**: declarative VM template system with CLI management tools
* **NEW**: full Proxmox VE 9.x series support with enhanced compatibility and performance optimizations
---
### Requirements & Compatibility
> The selector and the underlying scripts are designed for a **typical, up-to-date Proxmox host**.
> If your stack falls outside the matrix below, use at your own risk.
| | |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Platform** | 
*(fully supports latest Proxmox VE 9.x with enhanced compatibility)* |
| **CPU arch** | 
|
| **Privileges** | 
> **Heads-up** PECU does **not** support ARM / Raspberry Pi builds of Proxmox at this time.
> Community ports are welcome, but official testing is x86-64 only.
---
## Quick Start
### Direct execution (recommended)
> **New in 2025-05** – a tiny selector script fetches **all** tagged releases and
> lets you launch whichever version (Stable, Beta, Experimental…) you want.
```bash
bash <(curl -sL \https://raw.githubusercontent.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/refs/heads/main/scripts/pecu_release_selector.sh)
```
#### Release Selector
#### Release Selector - Premium Interface
#### PECU-Script
---
### Offline / local install
All releases ship a `.tar.gz` bundle:
```bash
VERSION="v2025.04.14" # pick any tag
wget https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/releases/download/$VERSION/PECU-${VERSION#v}.tar.gz
tar -xzf PECU-${VERSION#v}.tar.gz
cd PECU-${VERSION#v}/src
chmod +x proxmox-configurator.sh
sudo ./proxmox-configurator.sh
```
---
## What Is the Release Selector?
* `pecu_release_selector.sh` is a **new ASCII-driven menu** I built over the last few months.
It talks directly to the GitHub API, parses every tag, and sorts them by the
custom **`PECU-Channel`** labels I introduced (Stable, Beta, Preview, Experimental, Nightly).
The channels keep the list tidy and make it obvious which way the project is heading.
* Marking a build as **Experimental** instantly flags it orange in the menu,
so I can ship rough prototypes or quick-fix versions without confusing people who only want Stable releases.
lector.
* `pecu_release_selector_old.sh` still exists **only as a shim** that `exec`s the new script — **it will be removed on _05 July 2025_**.
---
## VM Templates System
**New in 2025.08** – PECU now includes a declarative VM template system with CLI management tools.
### Template Features
* **Declarative YAML templates** for common VM configurations (Windows Gaming, Linux Workstation, Media Server)
* **JSON Schema validation** ensuring template consistency and correctness
* **CLI management** with `templatectl.sh` for listing, validating, rendering, and applying templates
* **Safe rendering** – view `qm` commands before execution with `--dry-run`
* **Storage flexibility** – supports `local-lvm`, `local`, and auto-detection
* **CI/CD ready** – GitHub Actions workflow for automatic validation
### Quick Template Usage
```bash
# List available templates
src/tools/templatectl.sh list --channel Stable
# Validate all templates
src/tools/templatectl.sh validate templates/
# Preview commands (safe, no execution)
src/tools/templatectl.sh render templates/windows/windows-gaming.yaml \
--vmid 200 --storage-pool local-lvm --dry-run
# Apply template (creates VM)
sudo src/tools/templatectl.sh apply templates/windows/windows-gaming.yaml \
--vmid 200 --storage-pool local-lvm
```
### Available Templates
| Template | Channel | OS Type | Description |
|----------|---------|---------|-------------|
| `windows-gaming` | Stable | win11 | Windows 11 VM optimized for gaming with GPU passthrough support |
| `linux-workstation` | Stable | l26 | Linux workstation for development and productivity |
| `media-server` | Stable | l26 | Lightweight Linux VM for media services (Plex, Jellyfin, etc.) |
See [templates/README.md](templates/README.md) for detailed documentation.
---
## Features
| Category | Highlights |
| --------------------- | ---------------------------------------------------------------------------------------- |
| **Repositories** | Backup / restore `sources.list`, add "non-subscription" repo, edit with Nano. |
| **GPU Passthrough** | Wizard-style setup for NVIDIA, AMD, Intel; supports driverctl override; rollback option. |
| **Kernel Tweaks** | Add `pcie_acs_override`, `video=efifb:off`, or custom flags with risk prompts. |
| **Multi-GPU** | Detects multiple GPUs and lets you choose the one to passthrough. |
| **Intel iGPU (test)** | Experimental automatic isolation of iGPU functions. |
| **VM Templates** | Declarative YAML templates with CLI tools for common VM configurations. |
| **Template Validation** | JSON Schema validation and CI/CD integration for template quality assurance. |
| **Proxmox 9.x** | Full support for the latest Proxmox VE 9.x series with enhanced compatibility and performance optimizations. |
| **Logging** | Detailed `/var/log/pecu.log` with timestamps and automatic log rotation. |="center">
---
---
## Community & Contribution
PECU grows through clear bug reports, well-scoped ideas, and peer-reviewed code.
If you would like to get involved, choose the channel that best suits your needs:
| Purpose | Channel |
|---------|---------|
| **Bug reports / feature requests** | Use the GitHub [Issue tracker](../../issues). Please include the tag you were running, a concise description, and any relevant console output. |
| **Code contributions** | Fork the repository, branch from `main`, run `shellcheck`, keep commits focused, then open a Pull Request. |
| **Technical discussion and quick feedback** | Join the PECU Discord server: . The server is used for informal Q&A, brainstorming future features, and sharing configuration tips. |
| **Sustained support and early-access builds** | Patreon memberships are available at . Patrons receive preview builds, detailed implementation notes, and can vote on the development roadmap. |
---
### Support the Project
If PECU saves you time in daily operations and you wish to accelerate its development, consider a one-off donation:
Your support funds additional test hardware.
## License
**GPL-3.0** – see [LICENSE](LICENSE).
Feel free to fork, adapt, and share under the same terms.