proxmox/docs/01-getting-started/LIST_VMS_README.md

List Proxmox VMs Scripts

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Two scripts to list all Proxmox VMs with VMID, Name, IP Address, FQDN, and Description.

Scripts

1. list_vms.py (Python - Recommended)

Python script using the Proxmox API. More robust and feature-rich.

Features:

• Supports both API token and password authentication
• Automatically loads credentials from ~/.env file
• Retrieves IP addresses via QEMU guest agent or network config
• Gets FQDN from hostname configuration
• Handles both QEMU VMs and LXC containers
• Graceful error handling

Prerequisites:

pip install proxmoxer requests
# Or if using venv:
source venv/bin/activate
pip install proxmoxer requests

Usage:

Option 1: Using ~/.env file (Recommended)

# Create/edit ~/.env file with:
PROXMOX_HOST=your-proxmox-host
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-value
# OR use password:
PROXMOX_PASSWORD=your-password

# Then run:
python3 list_vms.py

Option 2: Environment variables

export PROXMOX_HOST=your-proxmox-host
export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_NAME=your-token-name
export PROXMOX_TOKEN_VALUE=your-token-value
python3 list_vms.py

Option 3: JSON config file

export PROXMOX_MCP_CONFIG=/path/to/config.json
python3 list_vms.py

2. list_vms.sh (Shell Script)

Shell script using pvesh via SSH. Requires SSH access to Proxmox node.

Prerequisites:

• SSH access to Proxmox node
• pvesh command available on Proxmox node
• Python3 for JSON parsing

Usage:

export PROXMOX_HOST=your-proxmox-host
export PROXMOX_USER=root
./list_vms.sh

Output Format

Both scripts output a formatted table:

VMID   | Name                    | Type | IP Address         | FQDN                    | Description
-------|-------------------------|------|-------------------|-------------------------|----------------
100    | vm-example              | QEMU | 192.168.1.100     | vm-example.local         | Example VM
101    | container-example       | LXC  | 192.168.1.101     | container.local         | Example container

How IP Addresses are Retrieved

For QEMU VMs:

1. First tries QEMU guest agent (network-get-interfaces)
2. Falls back to network configuration parsing
3. Shows "N/A" if neither method works

For LXC Containers:

1. Executes hostname -I command inside container
2. Filters out localhost addresses
3. Shows "N/A" if command fails or container is stopped

How FQDN is Retrieved

1. Gets hostname from VM/container configuration
2. For running VMs, tries to execute hostname -f command
3. Falls back to hostname from config if command fails
4. Shows "N/A" if no hostname is configured

Troubleshooting

Connection Timeout

• Verify Proxmox host is reachable: ping your-proxmox-host
• Check firewall rules allow port 8006
• Verify credentials in ~/.env are correct

Authentication Failed

• Verify API token is valid and not expired
• Check user permissions in Proxmox
• Try using password authentication instead

IP Address Shows "N/A"

• For QEMU: Ensure QEMU guest agent is installed and running in VM
• For LXC: Container must be running to execute commands
• Check network configuration in VM/container

FQDN Shows "N/A"

• Set hostname in VM/container configuration
• For running VMs, ensure hostname command is available

Examples

List all VMs

python3 list_vms.py

List VMs from specific host

PROXMOX_HOST=192.168.11.10 python3 list_vms.py

Using shell script

PROXMOX_HOST=192.168.11.10 PROXMOX_USER=root ./list_vms.sh

Notes

• Scripts automatically sort VMs by VMID
• Both QEMU VMs and LXC containers are included
• Scripts handle missing information gracefully (shows "N/A")
• Python script is recommended for better error handling and features