Proxmoxer

2.3.0 · active · verified Wed Apr 15

Proxmoxer is a Python wrapper around the Proxmox REST API v2, supporting Proxmox Virtual Environment (PVE), Proxmox Mail Gateway (PMG), and Proxmox Backup Server (PBS). It enables API calls over HTTPS, SSH, and the `pvesh` utility. The library dynamically creates attributes to mirror the Proxmox API structure, making interaction intuitive. The current stable version is 2.3.0, and it receives regular updates.

Warnings

breaking The `ProxmoxResourceBase` class has been removed in proxmoxer 2.x. While primarily an internal change, direct references to it will break.
Fix: Avoid direct use of `ProxmoxResourceBase`. Instead, use `ProxmoxResource` or the high-level API access methods.
breaking The `AuthenticationError` class was moved. Its previous path, `proxmoxer.backends.https.AuthenticationError`, is deprecated.
Fix: Update all imports and references to `AuthenticationError` to use `from proxmoxer import AuthenticationError`.
breaking The `ProxmoxHTTPTicketAuth` class and its associated `auth_token` and `csrf_token` arguments are no longer supported.
Fix: Migrate to using API tokens as the primary authentication method. If an existing token is passed as a password, `proxmoxer` will attempt to renew it. Refer to Proxmoxer documentation for API token usage.
gotcha SSL certificate verification (`verify_ssl`) defaults to `True`. For Proxmox instances using self-signed certificates, this will lead to SSL/TLS errors.
Fix: For development or testing environments, set `verify_ssl=False` in the `ProxmoxAPI` constructor. For production, ensure proper certificate handling by either installing the Proxmox CA certificate or providing a valid CA bundle path.
gotcha Backend dependencies (e.g., `requests` for HTTPS, `paramiko` for SSH) are optional and not installed by default with `pip install proxmoxer`.
Fix: Install the necessary dependencies manually (e.g., `pip install requests`) or use the extras syntax (e.g., `pip install proxmoxer[https]`) for your chosen backend.

Install

pip install proxmoxer Base Installation
pip install proxmoxer[https] With HTTPS Backend (includes requests)
pip install proxmoxer[ssh_paramiko] With SSH (Paramiko) Backend
pip install proxmoxer[openssh] With SSH (OpenSSH) Backend

Imports

ProxmoxAPI
```
from proxmoxer import ProxmoxAPI
```
AuthenticationError
wrong:
```
from proxmoxer.backends.https import AuthenticationError
```
correct:
```
from proxmoxer import AuthenticationError
```
The AuthenticationError class was moved from the backends.https module to the top-level proxmoxer package in version 2.x.

Quickstart

This quickstart demonstrates how to connect to a Proxmox host using the HTTPS backend and retrieve a list of nodes and QEMU virtual machines. Credentials are loaded from environment variables for security. Remember to install `requests` for the HTTPS backend to work.

import os
from proxmoxer import ProxmoxAPI

PROXMOX_HOST = os.environ.get('PROXMOX_HOST', 'your_proxmox_host')
PROXMOX_USER = os.environ.get('PROXMOX_USER', 'root@pam')
PROXMOX_PASSWORD = os.environ.get('PROXMOX_PASSWORD', 'your_secret_password')
# For self-signed certificates in dev/test, set verify_ssl=False. 
# For production, ensure proper certificate verification.
PROXMOX_VERIFY_SSL = os.environ.get('PROXMOX_VERIFY_SSL', 'False').lower() == 'true'

if not PROXMOX_HOST or not PROXMOX_USER or not PROXMOX_PASSWORD:
    print("Please set PROXMOX_HOST, PROXMOX_USER, and PROXMOX_PASSWORD environment variables.")
    exit(1)

try:
    proxmox = ProxmoxAPI(
        PROXMOX_HOST,
        user=PROXMOX_USER,
        password=PROXMOX_PASSWORD,
        verify_ssl=PROXMOX_VERIFY_SSL
    )

    print(f"Connected to Proxmox at {PROXMOX_HOST} as {PROXMOX_USER}")

    print("\n--- Proxmox Nodes ---")
    for node in proxmox.nodes.get():
        print(f"Node: {node['node']} (Status: {node['status']})")

    print("\n--- QEMU VMs ---")
    for node in proxmox.nodes.get():
        for vm in proxmox.nodes(node['node']).qemu.get():
            print(f"  Node: {node['node']} - VMID: {vm['vmid']}, Name: {vm['name']}, Status: {vm['status']}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →