[ ~/proxmox-sdk/proxmoxer-comparison ]tty0

emerson@netdevops:~/proxmox-sdk$ diff proxmoxer proxmox-sdk

proxmoxer vs proxmox-sdk

Side-by-side comparison of two Python libraries for the Proxmox API.

proxmoxer is the established Python library for the Proxmox VE/PBS/PMG API. It has been the go-to choice since 2012, is production-proven across thousands of deployments, and underpins major automation tooling including the Ansible Proxmox collection and several Terraform providers.

proxmox-sdk is a newer library (2024, pre-release) that takes a different approach: it generates its API surface directly from the Proxmox API Viewer schema, ships a full FastAPI server alongside the Python SDK, and defaults to an in-memory mock mode so you can develop without a live cluster.

Both libraries support the same Proxmox authentication methods and backend transports. The right choice depends on your use case — the sections below lay out the trade-offs without embellishment.

›libraries

emerson@netdevops:~/proxmox-sdk$ cat libraries.md

proxmoxer

A thin, hand-written Python wrapper around the Proxmox REST API. Returns raw Python dicts (or the exact JSON your Proxmox node sends). Designed to be minimal: the main dependency for HTTPS access is the requests library.

proxmoxer is sync-first. Unofficial async wrappers exist in the community but are not part of the upstream package. It has no mock mode — every call targets a real Proxmox endpoint.

Its breadth covers Proxmox VE, Proxmox Backup Server, and Proxmox Datacenter Manager. The API surface is hand-maintained, which means it rarely breaks but can lag behind new Proxmox endpoints.

best for

  • ›Existing Ansible, Terraform, or shell-script automation that already uses proxmoxer
  • ›Simple scripts that need minimal dependencies in a production codebase
  • ›Projects where raw dict responses are fine and typing is not required
  • ›Environments where you always have a real Proxmox cluster to test against

proxmox-sdk

A code-generated Python SDK built from the Proxmox API Viewer schema. The same package ships a full FastAPI server (with Swagger UI at /docs), a CLI (pbx), and a Textual TUI — but the core SDK is usable standalone without any of those extras.

proxmox-sdk defaults to mock mode: an in-memory FastAPI server that responds to all 675 PVE 9.2 endpoints with auto-generated CRUD data. Switching to real mode proxies validated requests to a live Proxmox node.

Responses are Pydantic models, not raw dicts. The schema is refreshed weekly via a GitHub Actions workflow that detects API drift automatically. proxmox-sdk is pre-release (alpha) with low adoption and an API surface that may change between versions.

best for

  • ›Building a service or API layer on top of Proxmox that needs an OpenAPI surface
  • ›Developing and testing locally without a live Proxmox cluster (mock mode)
  • ›Projects that benefit from typed, Pydantic-validated Proxmox responses
  • ›Workflows that want a ready-made CLI or TUI for Proxmox operations

›comparison

emerson@netdevops:~/proxmox-sdk$ ./compare.sh proxmoxer proxmox-sdk

aspectproxmoxerproxmox-sdk
typePython libraryPython library + FastAPI server
first release20122024
maturityproduction, widely adoptedalpha, low adoption
licenseBSD-2-ClauseMIT
python2.7 / 3.x3.11+
response formatraw dict / JSONPydantic models
mock / offline devnoyes (default mode)
OpenAPI schemanoyes — 675 ops, PVE 9.2
FastAPI servernoyes (optional)
Swagger UI /docsnoyes
code generationno (hand-written)yes (Playwright + pipeline)
schema auto-syncnoyes — weekly GitHub Actions
auth: API tokenyesyes
auth: password + ticketyesyes
auth: OTP / TOTPyesyes
backend: HTTPSyesyes
backend: SSH (Paramiko)yesyes
backend: SSH (openssh)yesyes
backend: pvesh CLIyesyes
async supportthird-party onlyyes (native asyncio)
rate limitingnoyes (SlowAPI)
CLInoyes — pbx / proxmox-cli
TUInoyes (Textual)
Docker imagesnoyes (raw / nginx / granian)
deps footprintminimal (requests / paramiko)heavy (FastAPI, Pydantic, aiohttp)
ecosystem adoptionvery highvery low (new)
Ansible collectionyes (community.general)no
Terraform provideryes (telmate/proxmox)no

›when to choose

emerson@netdevops:~/proxmox-sdk$ ./recommend.sh

use proxmoxer when

  • ›Existing Ansible, Terraform, or shell-script automation that already uses proxmoxer
  • ›Simple scripts that need minimal dependencies in a production codebase
  • ›Projects where raw dict responses are fine and typing is not required
  • ›Environments where you always have a real Proxmox cluster to test against

use proxmox-sdk when

  • ›Building a service or API layer on top of Proxmox that needs an OpenAPI surface
  • ›Developing and testing locally without a live Proxmox cluster (mock mode)
  • ›Projects that benefit from typed, Pydantic-validated Proxmox responses
  • ›Workflows that want a ready-made CLI or TUI for Proxmox operations

If you need a library that works in production today, proxmoxer is the right choice. It has been battle-tested for over a decade, integrates with the broader Ansible and Terraform ecosystem, and adds almost no dependency weight to your project.

If you are building a new service that exposes Proxmox functionality through an API, or if you want to develop without a live Proxmox cluster, proxmox-sdk is worth evaluating. Its mock server, typed responses, and OpenAPI surface provide a different developer experience than proxmoxer — one aimed at service developers rather than script authors.

The two libraries are not mutually exclusive. proxmoxer handles direct Python-to-Proxmox calls; proxmox-sdk targets the layer above that, where you need an HTTP service front-end, auto-generated docs, or typed models for downstream consumers.

›install

emerson@netdevops:~/proxmox-sdk$ pip install

proxmoxer

shell
pip install proxmoxer

proxmox-sdk

shell
pip install proxmox-sdk

›links

emerson@netdevops:~/proxmox-sdk$ links