Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Python Wrapper for the Proxmox 2.x API (HTTP and SSH)

Project description

master branch: master_build_status master_coverage_status pypi_version pypi_downloads

develop branch: develop_build_status develop_coverage_status

What does it do and what’s different?

Proxmoxer is a wrapper around the Proxmox REST API v2.

It was inspired by slumber, but it is dedicated only to Proxmox. It allows not only REST API use over HTTPS, but the same api over ssh and pvesh utility.

Like Proxmoxia, it dynamically creates attributes which responds to the attributes you’ve attempted to reach.


pip install proxmoxer

To use the ‘https’ backend, install requests

pip install requests

To use the ‘ssh_paramiko’ backend, install paramiko

pip install paramiko

Short usage information

The first thing to do is import the proxmoxer library and create ProxmoxAPI instance.

from proxmoxer import ProxmoxAPI
proxmox = ProxmoxAPI('proxmox_host', user='admin@pam',
                     password='secret_word', verify_ssl=False)

This will connect by default through the ‘https’ backend.

You can also setup API Tokens which allow tighter access controls. API Tokens are also stateless, so they much better for long-lived programs that might have the standard username/password authentication timeout. API tokens can be created through the web UI or through the API.

from proxmoxer import ProxmoxAPI
proxmox = ProxmoxAPI('proxmox_host', user='admin', token_name='test_token', token_value='ab27beeb-9ac4-4df1-aa19-62639f27031e')

For SSH access, it is possible to use pre-prepared public/private key authentication and ssh-agent.

from proxmoxer import ProxmoxAPI
proxmox = ProxmoxAPI('proxmox_host', user='proxmox_admin', backend='ssh_paramiko')

Note: the ‘https’ backend needs the ‘requests’ library, the ‘ssh_paramiko’ backend needs the ‘paramiko’ library, and the ‘openssh’ backend needs the ‘openssh_wrapper’ library installed.

Queries are exposed via the access methods get, post, put and delete. For convenience two synonyms are available: create for post, and set for put.

Using the paths from the Proxmox REST API v2, you can create API calls using the access methods above.

for node in proxmox.nodes.get():
    for vm in proxmox.nodes(node['node']).openvz.get():
        print "{0}. {1} => {2}" .format(vm['vmid'], vm['name'], vm['status'])

>>> 141. => running
    101. => running
    102. => running
    140. => running
    126. => running
    113. => running

same code can be rewritten in the next way:

for node in proxmox.get('nodes'):
    for vm in proxmox.get('nodes/%s/openvz' % node['node']):
        print "%s. %s => %s" %  (vm['vmid'], vm['name'], vm['status'])

As a demonstration of the flexibility of usage of this library, the following lines accomplish the equivalent function:

proxmox.get('nodes/%s/openvz' % node['node'])
proxmox.get('nodes', node['node'], 'openvz')

Some more examples:

Listing VMs:

for vm in proxmox.cluster.resources.get(type='vm'):
    print("{0}. {1} => {2}" .format(vm['vmid'], vm['name'], vm['status']))

Listing contents of the local storage on the proxmox_node node (method 1):

node = proxmox.nodes('proxmox_node')

Listing contents of the local storage on the proxmox_node node (method 2):

node = proxmox.nodes.proxmox_node()

creating a new lxc container:

node = proxmox.nodes('proxmox_node')

The same lxc container can be created with options set in a dictionary. This approach allows adding ssh-public-keys without getting syntax errors.

newcontainer = { 'vmid': 202,
    'ostemplate': 'local:vztmpl/debian-9.0-standard_20170530_amd64.tar.gz',
    'hostname': 'debian-stretch',
    'storage': 'local',
    'memory': 512,
    'swap': 512,
    'cores': 1,
    'password': 'secret',
    'net0': 'name=eth0,bridge=vmbr0,ip=,gw=' }
node = proxmox.nodes('proxmox_node')

Uploading a template:

local_storage = proxmox.nodes('proxmox_node').storage('local')

Downloading rrd CPU image data to a file:

response = proxmox.nodes('proxmox').rrd.get(ds='cpu', timeframe='hour')
with open('cpu.png', 'wb') as f:

Example of usage of logging:

# now logging debug info will be written to stdout
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %(levelname)s:%(name)s: %(message)s')


1.1.0 (2020-05-22)

  • Addition (https): Added API Token authentication (John Hollowell)
  • Improvement (https): user/password authentication refreshes ticket to prevent expiration (CompileNix and John Hollowell)
  • Bugfix (ssh_paramiko): Handle empty stderr from ssh connections (morph027)
  • DEPRECATED (https): using auth_token and csrf_token (ProxmoxHTTPTicketAuth) is now deprecated. Either pass the auth_token as the password or use the API Tokens.

1.0.4 (2020-01-24)

  • Improvement (https): Added timeout to authentication (James Lin)
  • Improvement (https): Handle AnyEvent::HTTP status codes gracefully (Georges Martin)
  • Improvement (https): Advanced error message with error code >=400 (ssi444)
  • Bugfix (ssh): Fix pvesh output format for version > 5.3 (timansky)
  • Transfered development to proxmoxer organization

1.0.3 (2018-09-10)

1.0.2 (2017-12-02)

  • Tarball repackaged with tests

1.0.1 (2017-12-02)

  • LICENSE file now included in tarball
  • Added verify_ssl parameter to ProxmoxHTTPAuth (Walter Doekes)

1.0.0 (2017-11-12)

0.2.5 (2017-02-12)

0.2.4 (2016-05-02)

0.2.3 (2016-01-20)

0.2.2 (2016-01-19)

0.2.1 (2015-05-02)

0.2.0 (2015-03-21)

  • Https will now raise AuthenticationError when appropriate. (scap1784)
  • Preliminary python 3 compatibility. (wdoekes)
  • Additional example. (wdoekes)

0.1.7 (2014-11-16)

  • Added ignore of “InsecureRequestWarning: Unverified HTTPS request is being made…” warning while using https (requests) backend.

0.1.4 (2013-06-01)

  • Added logging
  • Added openssh backend
  • Tests are reorganized

0.1.3 (2013-05-30)

  • Added next tests
  • Bugfixes

0.1.2 (2013-05-27)

  • Added first tests
  • Added support for travis and coveralls
  • Bugfixes

0.1.1 (2013-05-13)

  • Initial try.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for proxmoxer, version 1.1.1
Filename, size File type Python version Upload date Hashes
Filename, size proxmoxer-1.1.1.tar.gz (18.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page