OpenTofu does not talk to Proxmox VE by itself: it needs a provider plugin that calls the Proxmox API. The short answer for 2026 is to use the community bpg/proxmox provider, create a dedicated API token, keep a cloud-image template or let the provider download an image, and describe each VM in a proxmox_virtual_environment_vm resource. This guide walks through that path with commands and HCL based on the providers’ own documentation. Facts were checked on 14 November 2026 against GitHub, the OpenTofu registry and the Proxmox wiki. Not tested yet: we did not run tofu apply against a cluster for this article, so treat the snippets as starting points and read the plan output before you apply.
What you need and what was checked on 14 November 2026
| Item | Detail |
|---|---|
| OpenTofu | Free, open source, MPL-2.0. GitHub lists v1.13.9 (5 November 2026) as the latest release |
| Proxmox VE | Free, open source. The Proxmox roadmap lists 9.2 as the current release |
Provider bpg/proxmox | MPL-2.0, v0.122.0 published 12 November 2026, repository active, listed in the OpenTofu registry |
Provider Telmate/proxmox | MIT, newest GitHub release v3.0.2-rc10 (30 August 2026), listed in the OpenTofu registry |
| Requirements (bpg docs) | Proxmox VE 9.x; OpenTofu 1.6+ supported but not exercised in the provider’s CI; TLS 1.3 on the API endpoint |
The bpg README states that Proxmox VE 8.x is supported with limits, 7.x is not supported, and that while the provider is on 0.x it does not guarantee backward compatibility between minor versions. Pin the version in your configuration for that reason.
Which Proxmox provider to pick
| Criterion | bpg/proxmox | Telmate/proxmox |
|---|---|---|
| Licence | MPL-2.0 | MIT |
| Newest release (14 Nov 2026) | v0.122.0, 12 Nov 2026 | v3.0.2-rc10, 30 Aug 2026 (a release candidate) |
| VM resource | proxmox_virtual_environment_vm | proxmox_vm_qemu |
| Containers | proxmox_virtual_environment_container | proxmox_lxc |
| Authentication | API token, auth ticket, or user and password | User and password, or pm_api_token_id and pm_api_token_secret |
| Stated target | Proxmox VE 9.x | No version statement in the README |
| Known limits in its own docs | Some operations need root@pam (see below) | README lists a disk size display mismatch and updates that show as failed tasks in the web UI |
For a new setup we would start with bpg because its documentation names Proxmox VE 9.x as the test target. Telmate is the older provider and is still maintained (its repository saw a push on 2 November 2026), so existing code that uses it does not need an urgent rewrite. Moving between the two means rewriting resources and importing state, so choose once.
Step 1: create a Proxmox user and API token
Do not point automation at root@pam with a password. The bpg documentation shows a dedicated user, a role and a token created with pveum on the Proxmox host:
pveum user add terraform@pve
pveum role add Terraform -privs "VM.Allocate VM.Clone VM.Config.CPU VM.Config.Memory VM.Config.Disk VM.Config.Network VM.Config.Cloudinit VM.Config.Options VM.Config.CDROM VM.PowerMgmt VM.Audit VM.GuestAgent.Audit Datastore.AllocateSpace Datastore.Audit Sys.Audit SDN.Use"
pveum aclmod / -user terraform@pve -role Terraform
pveum user token add terraform@pve provider --privsep=0The privilege list above is our shortened selection from the long example in the bpg docs. That example is described there as only an example, “likely too permissive for most use cases”, and the docs note that privileges changed in Proxmox VE 9.0. Review the list against the pveum privileges documentation and add what plan errors ask for. The provider docs also say to keep SDN.Use or SDN.Audit; without them bridges are hidden from the API and the provider fails with “interface not found”. The token secret is shown once, so store it in a secret manager and join it into one string: terraform@pve!provider=SECRET.
Limits of tokens, from the same docs: some operations are restricted to root@pam, including container bind mounts, PCI and USB passthrough without a resource mapping, virtiofs directories and the VM CPU architecture. If you need those, use password authentication, or the provider’s root_ticket option over SSH, and read the warning there that all calls under /nodes/ then run as root.
Step 2: configure the provider
Keep the token out of the files. The provider reads PROXMOX_VE_API_TOKEN, so the configuration only needs the endpoint:
terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
version = "~> 0.122.0"
}
}
}
provider "proxmox" {
endpoint = "https://10.0.0.2:8006/"
# insecure = true # only for a self-signed certificate in a lab
}export PROXMOX_VE_API_TOKEN='terraform@pve!provider=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
tofu inittofu init downloads the provider from the OpenTofu registry. SSH to the node is optional: per the provider docs it is only needed for uploading snippets, some file types, importing disks through source_file.path and LXC idmap entries. Creating, changing and deleting VMs goes through the API. If you do use SSH together with an API token, the docs say to set the SSH username in the ssh block and use an agent or key, because there is no password to inherit.
Step 3: get an image into Proxmox
There are two common routes. The first is the manual one from the Proxmox cloud-init guide: create a VM, import a cloud image, add a cloud-init drive and convert it to a template.
qm create 9000 --memory 2048 --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci
qm set 9000 --scsi0 local-lvm:0,import-from=/path/to/cloud-image.img
qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --boot order=scsi0
qm set 9000 --serial0 socket --vga serial0
qm template 9000The second route lets OpenTofu fetch the image itself with proxmox_virtual_environment_download_file and import it into the VM disk with import_from, as in the provider’s own example. Per the docs, this uses the API, not SSH. Note the file name trick from that example: the downloaded .img is saved with a .qcow2 name so Proxmox knows the format.
Step 4: describe a VM
This is a trimmed version of the example in the bpg resource documentation, with a cloud image downloaded and imported:
resource "proxmox_virtual_environment_download_file" "ubuntu_image" {
content_type = "import"
datastore_id = "local"
node_name = "pve"
url = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
file_name = "jammy-server-cloudimg-amd64.qcow2"
}
resource "proxmox_virtual_environment_vm" "app01" {
name = "app01"
node_name = "pve"
vm_id = 4321
tags = ["tofu", "ubuntu"]
agent {
enabled = false # switch to true only when qemu-guest-agent runs in the VM
}
stop_on_destroy = true
cpu {
cores = 2
type = "x86-64-v2-AES"
}
memory {
dedicated = 2048
}
disk {
datastore_id = "local-lvm"
import_from = proxmox_virtual_environment_download_file.ubuntu_image.id
interface = "scsi0"
}
initialization {
ip_config {
ipv4 {
address = "dhcp"
}
}
user_account {
username = "ubuntu"
keys = [trimspace(file("~/.ssh/id_ed25519.pub"))]
}
}
network_device {
bridge = "vmbr0"
}
}To clone your own template instead, add a clone block with the template’s vm_id and drop the import_from disk. The docs warn that if you change any attribute of a cloned disk you must also restate the other non-default values (size, discard, cache), otherwise the schema defaults overwrite what the template had.
Then run the usual cycle:
tofu fmt
tofu validate
tofu plan -out=vm.plan
tofu apply vm.planCommon problems from the provider docs
- Waits of up to 15 minutes on create. With
agent.enabled = truethe provider waits forqemu-guest-agent. Cloud images usually do not ship it; install it through cloud-init or keep the agent disabled. A clone inherits the agent flag of its template, so setagent { enabled = false }explicitly on the clone if the agent is not running. - VM stuck on destroy. Without the agent, shutdown uses ACPI and some guests ignore it.
stop_on_destroy = truestops the VM instead. - Datastore
local-lvmdoes not exist. It is the default for the cloud-init and TPM disks. Setdatastore_idin those blocks if your storage is named differently. - 403 or “only root can set ‘arch'”. You hit an operation restricted to
root@pam; see the token section above. - TLS errors. The bpg provider expects TLS 1.3 on the API endpoint; the
min_tlsargument can allow older versions. - Existing VMs. They can be brought under management with
tofu import proxmox_virtual_environment_vm.app01 pve/4321(node name and VM ID).
Limitations of this approach
OpenTofu creates the VM; it does not configure what runs inside it. For packages and services pair it with Ansible, or pass a cloud-init file through the provider. The provider is on 0.x, so read release notes before upgrading, and keep the state file in a backed-up location because it holds the VM IDs OpenTofu believes it owns. If you are still deciding between OpenTofu and HashiCorp’s tool, see Terraform vs OpenTofu and the Terraform page; the bpg docs address both tools. QEMU is the layer underneath Proxmox VMs, and the virtualization and container tools hub lists alternatives.
Who this fits
| Situation | Fit |
|---|---|
| Homelab or small cluster on Proxmox VE 9, many similar VMs | Good: one file per VM, repeatable rebuilds |
| Proxmox VE 7.x | Not supported by bpg; upgrade first |
| A handful of long-lived pet servers | Probably overkill; the web UI is faster |
| PCI passthrough or bind mounts through automation | Possible, but needs root@pam rights; weigh the security cost |
FAQ
Does OpenTofu work with Proxmox?
Yes, through a provider. Both bpg/proxmox and Telmate/proxmox are listed in the OpenTofu registry; the bpg docs state OpenTofu 1.6+ is supported but not exercised in its CI.
What is the best OpenTofu Proxmox provider?
For Proxmox VE 9.x, bpg/proxmox, because it targets 9.x and had a release two days before this check. Telmate/proxmox is the older MIT-licensed option whose newest release is a release candidate.
Can I create LXC containers with OpenTofu?
Yes. bpg uses proxmox_virtual_environment_container and Telmate uses proxmox_lxc. Some container features, such as bind mounts, need root@pam rather than a token.
How do I use cloud-init with OpenTofu on Proxmox?
Use the initialization block for the user, SSH key and IP settings, and a user_data_file_id snippet for custom cloud-config. Snippet upload needs SSH access to the node.
Do I need SSH to the Proxmox node?
Not for creating, changing or deleting VMs. It is needed for snippets, some file uploads and importing a local disk file.
Can I use the Terraform provider with OpenTofu?
For bpg, the documentation addresses Terraform and OpenTofu together and the provider is published in both registries. Check the version requirements of the provider you pick before you upgrade the tool.
Last updated: 14 November 2026 · ITForgePro editorial team. Licence, version and platform details are checked against each developer's official documentation.





