Proxmox VE 9.1 OCI Containers: Deploy Docker Images as LXC

Proxmox VE 9.1's OCI container support lets you pull any Docker-compatible image and run it as an LXC container without building custom templates from scratch. The result is a faster, more flexible way to deploy workloads that previously required either a full VM or a hand-rolled LXC template.

Key Takeaways

• OCI Images — Any Docker-compatible image can now be deployed as an LXC container without custom templates.
• Template-Free — Use pct with the --image flag to pull directly from registries.
• Resource Control — OCI containers behave like regular LXCs, so CPU, memory, and storage limits apply normally.
• Tradeoff — OCI containers share the host kernel, so kernel-level features like GPU passthrough or custom modules may not be available.
• Best Fit — Ideal for stateless workloads, microservices, and development environments where rapid deployment matters more than kernel customization.

Why OCI Containers Matter for Proxmox

For years, Proxmox users have been stuck with a limited set of LXC templates — mostly Debian and Ubuntu — and had to either build custom templates or run full VMs when they needed specific base images. The OCI container feature in Proxmox VE 9.1 changes that dynamic entirely.

The core idea is simple: instead of downloading a pre-built LXC template, you pull a standard OCI image (the same format Docker uses) and run it directly as an LXC container. This means you can deploy anything from Build a Private Cloud at Home with Proxmox VE to Build a Software-Defined Datacenter with Proxmox VE — or any workload in between — using the same image format you already know from Docker and Kubernetes.

The practical benefit is speed and flexibility. If you need a Redis container, a PostgreSQL container, or even a custom-built image from your own registry, you no longer need to convert it to an LXC template format. You just pull it and run it.

How to Deploy an OCI Container in Proxmox

Deploying an OCI container is straightforward with the pct command-line tool. Here's the basic workflow:

# Pull an OCI image and create a new container
pct create 100 docker.io/library/nginx:latest \
  --ostype=other \
  --rootfs local-lvm:4 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
  --unprivileged=1

The pct create command does two things at once: it pulls the image from the specified registry and creates a new LXC container with that image as its root filesystem. The --ostype=other flag tells Proxmox not to apply any special template-specific configuration, and --unprivileged=1 gives you the default security model that most users prefer.

If you want more control over the deployment, you can also use the Proxmox web interface. Navigate to Datacenter → Storage → Images, select your storage backend, and click Import OCI Image. This is particularly useful when you're working with private registries or need to configure authentication.

Configuring OCI Containers for Production

Once your OCI container is running, it behaves like any other LXC container. You can attach it to VLANs using the same bridge configuration you'd use for regular containers, as described in Configuring VLANs on Proxmox with Linux Bridges. You can also monitor it with Cockpit on Proxmox: Manage KVM, LXC, and Docker in One UI if you prefer a graphical interface.

Here's a typical configuration for a production-grade OCI container:

# Set resource limits
pct set 100 --cpu 2
pct set 100 --memory 2048
pct set 100 --swap 512

# Configure networking
pct set 100 --net0 name=eth0,bridge=vmbr0,ip=10.0.1.100/24,gw=10.0.1.1

# Set up a backup
pct backup 100 --mode=stop

The key thing to remember is that OCI containers are still LXCs under the hood. They share the host kernel, which means you get the performance benefits of containers but also the limitations. If you need kernel modules or custom kernel features, you'll want to stick with VMs or use traditional LXC templates.

OCI Containers vs Traditional LXC Templates

Not every workload benefits from the OCI approach. Here's a comparison to help you decide:

Feature	OCI Container	Traditional LXC Template
Base image	Any Docker-compatible image	Debian/Ubuntu/Alpine
Deployment speed	Fast (pull and run)	Moderate (template-based)
Kernel features	Limited (host kernel)	Full (can customize)
Customization	Easy (modify image)	Moderate (rebuild template)
Storage overhead	Lower (shared layers)	Higher (full template)
Best for	Stateless workloads	Stateful workloads

If you're running Running Docker Inside LXC Containers on Proxmox or LXC Dev Environments on Proxmox Replace Docker Desktop, you'll find that OCI containers fit naturally into that ecosystem. They're essentially the same concept, just with better integration into the Proxmox management layer.

Real-World Gotcha: Network Configuration

One thing that caught me off guard when I first started using OCI containers is the network configuration. Because OCI containers pull their root filesystem from a remote image, the network configuration inside the container might not match your Proxmox host's expectations.

The solution is to configure the network at the Proxmox level rather than inside the container. Use the --net0 flag when creating the container, and let Proxmox handle the IP address assignment. This avoids conflicts and makes it easier to manage multiple containers on the same network.

When to Use OCI Containers

OCI containers are particularly well-suited for:

• Development environments — Spin up a fresh container with the exact image you need, run your tests, and tear it down.
• Microservices — Each service gets its own container with the right base image, without template management overhead.
• Stateless workloads — If your workload doesn't need persistent storage or custom kernel features, OCI containers are ideal.
• Rapid deployment — Pull and run in seconds, not minutes.

For stateful workloads or when you need specific kernel features, you might prefer traditional LXC templates or VMs. But for most modern workloads, OCI containers offer the best balance of speed and flexibility.

Conclusion

OCI containers in Proxmox VE 9.1 give you the flexibility of Docker with the management simplicity of LXC. You can now deploy any container image without building custom templates, which speeds up development and reduces operational overhead. If you're starting a new project or looking to modernize your homelab, OCI containers are worth trying. For production workloads that need specific kernel features, you'll still want traditional LXC templates or VMs, but the OCI approach is a powerful addition to your toolkit.