proxmoxer

library2.3.0pypypi✓ verified 87d ago

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.

http-networking devops

pip install proxmoxer

package ↗homepage ↗

INSTALL

IMPORT

SIG · PROXMOXER

proxmoxer

http-networkingpythonv2.3.0

Install

1.5s avg

Import

83ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.980 runs

installs and imports cleanly · install 0.0s · import 0.086s · 17.9MB

glibc

py 3.10–3.980 runs

installs and imports cleanly · install 1.5s · import 0.080s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ProxmoxAPI

✓ from proxmoxer import ProxmoxAPI

AuthenticationError

✓ from proxmoxer import AuthenticationError

✗ from proxmoxer.backends.https import AuthenticationError

The AuthenticationError class was moved from the backends.https module to the top-level proxmoxer package in version 2.x.

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}")

Debug

Known issues

breakingThe `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.

affects: >=2.0.0

breakingThe `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`.

affects: >=2.0.0

breakingThe `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.

affects: >=2.0.0

gotchaSSL 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.

affects: All versions

gotchaBackend 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'proxmoxer'

The 'proxmoxer' library or its required backend dependencies (e.g., 'requests' for HTTPS, 'paramiko' for SSH) are not installed in the Python environment.

fix

Install 'proxmoxer' and its necessary backend dependencies using pip: `pip install proxmoxer requests` (for HTTPS backend) or `pip install proxmoxer paramiko` (for SSH backend).

proxmoxer.backends.https.AuthenticationError: Couldn't authenticate user:

The provided username, password, realm, or API token is incorrect, lacks the necessary permissions, or SSL certificate verification is failing due to self-signed certificates.

fix

Double-check the credentials (username, password, realm, or API token) and ensure the user has appropriate permissions on the Proxmox server. If using a self-signed SSL certificate, initialize `ProxmoxAPI` with `verify_ssl=False`.

proxmoxer.core.ResourceException: 500 Internal Server Error: <Proxmox API message>

The 'proxmoxer' call successfully reached the Proxmox API, but the API itself returned a server-side error (HTTP 500) indicating an issue with the requested operation, such as trying to create a VM with an ID that already exists, or other configuration problems on the Proxmox server.

fix

Examine the specific error message returned by the Proxmox API (e.g., 'unable to find configuration file for VM', 'VM 100 already exists') to identify and correct the underlying Proxmox configuration or state issue.

AttributeError: 'NoneType' object has no attribute 'get'

A 'proxmoxer' method returned 'None' instead of an expected Proxmox API resource object, typically because the requested resource (e.g., a VM, node, or storage) does not exist or an earlier API call failed to return a valid object.

fix

Add checks to ensure that the results of 'proxmoxer' API calls are not 'None' before attempting to access their attributes. Verify the existence of resources before operating on them.

Upgrade

Version history

2.3.0latest on PyPI · released Mar 4, 2026

Audit

Dependencies

requestsoptionalRequired for the 'https' backend for making HTTP API calls.

paramikooptionalRequired for the 'ssh_paramiko' backend for SSH-based API access.

openssh_wrapperoptionalRequired for the 'openssh' backend for SSH-based API access.

Agent activity

19 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/proxmoxer/ ↗

homepagehttps://proxmoxer.github.io/docs/ ↗