NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Go modules
Go modules, #3037 by repository stars
Latest stable
v0.8.2
Last release 17 days ago
05 Nov 2026
Ships fairly regularly
a new release about every 4 weeks
Nearly every release is documented
notes for 20 of 21 stable releases
Nothing withdrawn
no release was ever pulled
5 years old
158 releases · first in 2021
Drag across the ruler to compare, or tap a release to open it.
Nothing published for this version
docs: add vm-template example, document the options-vs-config split by @luthermonson in https://github.com/luthermonson/go-proxmox/pull/345
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.8.1...v0.8.2
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Nothing published for this version
`AgentFileWrite` no longer double-encodes content (#343). It base64-encoded the payload *and* sent PVE's encode=1, so PVE encoded it a second time and
AgentFileWrite no longer double-encodes content (#343). It base64-encoded the payload and sent PVE's encode=1, so PVE encoded it a second time and QGA's single decode left base64 text on disk — corrupting any file written this way (configs, keys). Now sends the base64 payload with encode=0 so QGA reproduces the original bytes. Binary-safe.`VirtualMachine.Delete` signature change — gains a second parameter *VirtualMachineDeleteOptions. Pass nil to preserve existing behaviour. See migrati
VirtualMachine.Delete signature change — gains a second parameter *VirtualMachineDeleteOptions. Pass nil to preserve existing behaviour. See migration/v0.8.0.md for details and before/after examples.
// before
task, err := vm.Delete(ctx)
// after
task, err := vm.Delete(ctx, nil) // same behaviour
task, err := vm.Delete(ctx, &proxmox.VirtualMachineDeleteOptions{
Purge: true,
DestroyUnreferencedDisks: true,
})
VirtualMachineDeleteOptions — pass purge, skiplock, destroy-unreferenced-disks to VirtualMachine.Delete (#340)VirtualMachine.Ping now correctly propagates config-fetch errors (#339)errors.Is) (#341)See migration/v0.8.0.md.
Full changelog: https://github.com/luthermonson/go-proxmox/compare/v0.7.1...v0.8.0
AgentNetworkIPAddress.MacAddress deprecated → read iface.HardwareAddress (the QGA schema has never had a per-IP mac-address field). Closes #336.
v0.7.1 is a correctness patch. A full audit of every exported response type in types.go against PVE's apidoc.json and QGA's qga/qapi-schema.json surfaced eight long-standing schema mismatches — six of them silently no-op'd on the wire (wrong JSON tag, wrong scalar type, or a field name PVE never emitted). The apparent breaks below are functionally additive: the new field is the first one that has ever worked.
Two source-level breaks, both on StorageContent. See migration/v0.7.1.md for the full upgrade walkthrough.
| Change | Upgrade |
|---|---|
StorageContent.Encryption (string, tag encryption) → StorageContent.Encrypted (tag encrypted) |
rename the field reference; old value was always "" because the tag never matched the upstream key |
StorageContent.Verification string → *StorageContentVerification{State, UPID} |
dereference and read .State / .UPID; old value was always "" because PVE returns a nested object |
The Go field still exists and code still compiles; only the wire format changed. Switch to the replacement to get real behavior.
AgentNetworkIPAddress.MacAddress deprecated → read iface.HardwareAddress (the QGA schema has never had a per-IP mac-address field). Closes #336.FirewallNodeOption.Ntp / FirewallVirtualMachineOption.Ntp deprecated → use NDP. The PVE option is ndp (Neighbor Discovery Protocol); ntp was a typo shipped since v0.1.x and never had any effect.Tags fixed so the fields finally unmarshal from PVE:
CephMonMap.DisallowedLeaders — strip trailing ": " inside the quoted tagCephMonMap.RemovedRanks — sameFirewallRule.IcmpType — icmp_type → icmp-type (ICMP rules now round-trip correctly)NewClient(...) with no options still behaves identically to v0.7.0WithProxy, WithRetry, WithEagerAuth, …) unchangedSee https://github.com/luthermonson/go-proxmox/compare/v0.7.0...v0.7.1 once tagged.
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.7.0...v0.7.1
v0.7.0 is the major cleanup release. Three years of accumulated patterns get resolved into a consistent shape:
v0.7.0 is the major cleanup release. Three years of accumulated patterns get resolved into a consistent shape:
mtunnelwebsocket builders and file-restore/download). The v0.6.0 release sat at 81%; the v0.7.x cycle closed the cluster gap entirely with the SDN sweep (#320), the bulk-action / ceph-flags / qemu-cpu-models / options / log / notifications / HA arm-disarm cleanup (#322), and the rest.WithTimeout, WithInsecureSkipVerify, WithRootCAs, WithRootCAFile, WithClientCertificate, WithOTP, WithDefaultRealm, WithEagerAuth, WithProxy, WithProxyFromEnvironment, WithRetry (+ helpers), WithRequestInterceptor. All compose with WithHTTPClient regardless of option order. README has lab + production usage examples.parent.Resource(id) → *Resource getter shape that ceph already used in v0.6.0. The full inventory is in AGENTS.md.*T; ~25 bool-on-wire fields are now IntOrBool so they round-trip both true/false and 1/0. proxmox.Ptr(v) is the inline helper for the pointer fields.VirtualMachineConfig / ContainerConfig. Every numbered Net0..9, SCSI0..30, IDE0..3, SATA0..5, VirtIO0..15, USB0..14, HostPCI0..9, IPConfig0..9, Numa0..9, Parallel0..2, Serial0..3, Unused0..9 is gone. The maps populated by UnmarshalJSON (Nets, SCSIs, IPConfigs, …) are now the authoritative shape. PVE actually returns more indices than the explicit fields ever covered (net0..net31, scsi0..scsi30, unused0..unused255) — the old shape was silently dropping data.proxmox.CSV type for PVE fields serialized as comma-joined strings on the wire (most notably SDNZone.Nodes and .Peers).Subdirs methods on *Cluster and *Node for ACL-filtered directory-index probes. Use them to discover what an API token actually has permission to read without try-and-403 against every endpoint.This is a heavy release for source compatibility. The breaks are concentrated in three areas: the snapshot/firewall instance-pattern refactors, the dropped indexed device fields, and the config-struct pointerization sweep. Most fixes are mechanical.
Read migration/v0.7.0.md for the complete walkthrough — themed sections with before/after code for each break. The short version:
| Theme | Fix shape |
|---|---|
| Snapshots refactored | vm.DeleteSnapshot(ctx, "s") → vm.Snapshot("s").Delete(ctx); same pattern for Get/Update/Rollback/Config. Snapshots(ctx) returns []*VirtualMachineSnapshot. |
| Firewall rules refactored | vm.FirewallGetRule(ctx, 0) → vm.FirewallRule(ctx, 0). vm.FirewallRulesUpdate(ctx, rule) → rule.Update(ctx, opts). Same on *Container and *Node. |
| Indexed device fields | cfg.Net0 = "..." → cfg.Nets["net0"] = "..." (or send via VirtualMachineOption{Name: "net0", Value: "..."}). All Merge* helpers gone — the maps ARE the authoritative form. |
| Pointerized config fields | cfg.Memory = StringOrInt(4096) → cfg.Memory = proxmox.Ptr(StringOrInt(4096)). Full field list in the migration doc. |
| Bool → IntOrBool | opts.Enable = true → opts.Enable = proxmox.IntOrBool(true). Full list in migration doc. |
Client no longer comparable |
clientA == clientB (value comparison) doesn't compile. Pointer comparison still works. |
If you're upgrading from v0.5.x, also read migration/v0.6.0.md for the small set of v0.6.0 breaks.
NewClient(url, WithCredentials(...)) and NewClient(url, WithAPIToken(...)) with no other options — every new client field has a zero-value-safe code path. Upgrading without adopting any new option produces no behavior change.WithEagerAuth, the existing /access/ticket-after-401 sequence is unchanged.Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.6.0...v0.7.0
feat(pools): 100% endpoint coverage; migrate Update/Delete to non-deprecated paths by @luthermonson in https://github.com/luthermonson/go-proxmox/pull…
This is a coverage-and-correctness release. v0.6.0 lifts overall PVE API coverage substantially — /access, /pools, /nodes/{qemu,lxc,ceph,sdn,disks,apt,services,subscription,replication,time,dns,certificates,storage,agent,disks}, and /cluster/{acme,jobs,mapping,metrics,notifications} are now fully or nearly fully wrapped — and fixes a handful of latent bugs that hand-written PVE response assumptions had been hiding.
A new mage endpoints:coverage tool is included for tracking progress against the live PVE schema. AGENTS.md codifies the conventions (singleton-vs-instance handles, pointer fields for PVE-defaulted attributes) used across the new wrappers.
Four exported-surface changes require source updates:
Container.Delete requires options// before
task, err := container.Delete(ctx)
// after
task, err := container.Delete(ctx, nil)
// or, to exercise the new flags:
task, err := container.Delete(ctx, &proxmox.ContainerDeleteOptions{
Force: proxmox.IntOrBool(true),
Purge: proxmox.IntOrBool(true),
DestroyUnreferencedDisks: proxmox.IntOrBool(true),
})
Closes #149 — previously there was no way to force-delete a locked container or purge job entries. See #262.
Container.UpdateSnapshot requires options// before
err := container.UpdateSnapshot(ctx, "snap1")
// after
err := container.UpdateSnapshot(ctx, "snap1", nil)
// or to set a description:
err := container.UpdateSnapshot(ctx, "snap1", &proxmox.ContainerSnapshotUpdateOptions{
Description: "pre-upgrade baseline",
})
From #277.
CephMon reshapeCephMon was previously the /cluster/ceph status row shape; in v0.6.0 it is the instance handle for /nodes/{node}/ceph/mon/{monid} endpoints. The cluster-status reader fields (CrushLocation, Priority, Weight, PublicAddr, PublicAddrs) are gone.
If you were reading mon status from /cluster/ceph results, the equivalent shape now lives in the appropriate cluster ceph response type. For the node-level mon API:
mon := node.CephMon("0") // *CephMon instance handle
task, err := mon.Delete(ctx) // node-level mon operations
From the /nodes/{node}/ceph 100% sweep — see #307.
SDNZone.Nodes type change + new CSV typePVE returns nodes (and peers) as a comma-joined string, not a JSON array. v0.5.x's []string typing caused cluster.SDNZones() to fail outright on any zone with assigned nodes:
json: cannot unmarshal string into Go struct field SDNZone.nodes of type []string
// before — actually broken at runtime
zones, _ := cluster.SDNZones(ctx)
for _, n := range zones[0].Nodes { ... } // []string
// after
zones, _ := cluster.SDNZones(ctx)
for _, n := range zones[0].Nodes { ... } // proxmox.CSV — still iterates fine
// callers passing zone.Nodes to []string-typed APIs need an explicit conversion:
manyNodes := []string(zones[0].Nodes)
CSV is a []string named type with custom Marshal/Unmarshal that accepts both "a,b,c" and ["a","b","c"] on the wire and emits comma-joined strings. From #297 (thanks @kernel-sanders).
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.5.1...v0.6.0
pins go-diskfs at v1.9.3 to fix joliet bugs
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.5.0...v0.5.1
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
feat: add Joliet extension to cloud-init ISO for Windows support by @luthermonson in https://github.com/luthermonson/go-proxmox/pull/256
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.4.1...v0.5.0
Update VNet Tag type to uint32 and add max VNet Tag test case by @kernel-sanders in https://github.com/luthermonson/go-proxmox/pull/244
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.4.0...v0.4.1
Nothing published for this version
Nothing published for this version
fix: vm merge devices by @sergelogvinov in https://github.com/luthermonson/go-proxmox/pull/232
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.3.2...v0.3.3
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
fix: simplify network interface retrieval in AgentGetNetworkIFaces by @alperencelik in https://github.com/luthermonson/go-proxmox/pull/230
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.3.1...v0.3.2
Nothing published for this version
fix: duplicated func by @sergelogvinov in https://github.com/luthermonson/go-proxmox/pull/227
fixes broken v0.3.0
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.3.0...v0.3.1
DO NOT USE broke release due to CI not catching dupe methods, please use v0.3.1
DO NOT USE broke release due to CI not catching dupe methods, please use v0.3.1
Minor API changed in the #224 and added concept of New to reduce API calls
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.2.4...v0.3.0
fix(access): 🐛 add useroptions type and fix user update function by @kernel-sanders in https://github.com/luthermonson/go-proxmox/pull/216
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.2.3...v0.2.4
Nothing published for this version
fix: add correct RRD Data format and fix the variadic function by @dragonis41 in https://github.com/luthermonson/go-proxmox/pull/179
omitempty and bool values conflicting with Proxmox API defaults by @kernel-sanders in https://github.com/luthermonson/go-proxmox/pull/210Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.2.2...v0.2.3
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Fix link in README.md by @sirredbeard in https://github.com/luthermonson/go-proxmox/pull/173
api2/json/cluster/ceph/status endpoint by @justusbunsi in https://github.com/luthermonson/go-proxmox/pull/186Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.2.1...v0.2.2
Nothing published for this version
Nothing published for this version
Nothing published for this version
Fix VirtualMachine.IsPaused by @rybnico in https://github.com/luthermonson/go-proxmox/pull/169
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.2.0...v0.2.1
Nothing published for this version
Nothing published for this version
Nothing published for this version
Term/VNC features changed from string channels to []byte channels
Clone functions when CloneOptions.NewID is set by @rybnico in https://github.com/luthermonson/go-proxmox/pull/160Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.1.1...v0.1.2
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
fix: CPUInfo.MHZ type error by @im-zhou in https://github.com/luthermonson/go-proxmox/pull/153
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.1.0...v0.1.1
Nothing published for this version
This is the first official non-beta release. We will continue to work on the client and add more endpoints but the basic functionality has worked for
This is the first official non-beta release. We will continue to work on the client and add more endpoints but the basic functionality has worked for years and we will consider ourselves out of beta. Thanks to everyone who contributed!
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.0.0-beta6...v0.1.0
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
🐛fix: password endpoint client method by @alperencelik in https://github.com/luthermonson/go-proxmox/pull/130
Full Changelog: https://github.com/luthermonson/go-proxmox/compare/v0.0.0-beta5...v0.0.0-beta6
Nothing published for this version
Nothing published for this version
One column per quarter.