Proxmox dynamic inventory for Ansible
Branch: master
Clone or download
Latest commit 8c79997 Jan 25, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
playbook-example Added a playbook example Nov 23, 2016
.gitignore Add backwards compatability with openvz on Proxmox ver3 Mar 5, 2017 Updated changelog/contributions Jul 9, 2018
proxmox.json.dist Addition of JSON config sample Mar 17, 2017 Python3 compatibility Jan 13, 2019 Fix typo in URL Nov 23, 2016



Proxmox dynamic inventory for Ansible. Based on original plugin from Mathieu Gauthier-Lafaye

How does it work?

It will generate an inventory on the fly with all your VMs stored in your ProxmoxVE. Therefore, Ansible will be able to connect to all your VM.


Resolvable VM names: the inventory script collects the VM names (and not IP addresses!). That's why your computer must be able to resolve these names; either with the DNS server or your /etc/hosts


  • ProxmoxVE cluster: if your have a ProxmoxVE cluster, it will gather the whole VM list from your cluster
  • Advanced filtering: you can filter the VM list based in their status or a custom tag included in the Notes field


  • Added option to ignore invalid SSL certificate (by @bmillemathias) PR
  • Compatible with a Proxmox cluster (by @xezpeleta)
  • Added group 'running' (by @xezpeleta)
  • Added backwards compatibility with openvz and Proxmox3 (@isindir) [#1]
  • Added optional JSON configuration file (@nmaggioni) [#2]
  • Added backwards compatibility with python 2.6 (@isindir) [#3]
  • Handle cases where node is unavailable (@andor44) [#7]


Download to /etc/ansible/ directory:

cd /etc/ansible
sudo wget
sudo chmod +x

Let's test it:

python /etc/ansible/ \
  --url=https://<your-proxmox-url>:8006/ \
  --username=<proxmox-username> \
  --password=<proxmox-password> \
  --trust-invalid-certs \
  --list --pretty

If you get a list with all the VM in your Proxmox cluster, everything is ok.

I suggest you to use environment variables to store Proxmox credentials:

# You also can do that using the file
# Run the command: "source"
export PROXMOX_USERNAME=apiuser@pve
export PROXMOX_PASSWORD=apiuser1234

You may also save your settings in a JSON file with the same name of the Python script, in its same folder (e.g.: if the downloaded script is /etc/ansible/, the configuration file will be /etc/ansible/proxmox.json):

    "url": "",
    "username": "apiuser@pve",
    "password": "apiuser1234",
    "validateCert": false

So now you can check it again without credential parameters:

python /etc/ansible/ --list --pretty

Once you get this working, you can include the dynamic inventory in your ansible commands:

# Ping: connect to all VM in Proxmox using root user
ansible -i /etc/ansible/ all -m ping -u root


If you prefer, you can limit the commands to the group "running":

# Run a playbook in every running VM in Proxmox
ansible-playbook -i /etc/ansible/ --limit='running' playbook-example/playbook.yml

Thanks to Matt Harris, you can now use the Notes field in Proxmox to add a host to a group:

Added support for Proxmox VE 4.x Added support for using the Notes field of a VM to define groups and variables: A well-formatted JSON object in the Notes field will be added to the _meta section for that VM. In addition, the "groups" key of this JSON object may be used to specify group membership:

{ "groups": ["utility", "databases"], "a": false, "b": true }

For instance, you can use the following JSON code in a VM host:

{ "groups": ["windows"] }

So if you want to exclude Windows machines, you could do the following:

# Run a playbook in every running Linux machine in Proxmox
ansible-playbook -i /etc/ansible/ --limit='running,!windows' playbook-example/playbook.yml


Show Linux distribution version for every VM in Proxmox cluster:

 ansible all -i /etc/ansible/ --limit 'running,!windows' -m setup -u root -a 'filter=ansible_distribution_*'

Check more info about Ansible setup module