Container creation on Proxmox VE

build_container is the call in a container script that turns the resolved settings into a running container with the application in it. On a Proxmox VE host it lives in pve/backend.func. On an Incus host core/build.func loads the Incus backend instead; see Platforms and the Incus guide.

Before anything is createdCopy Anchor Link

start runs these checks before the menu opens. Each one stops the run with its own message and exit code.

The storage check offers a fix when it can: it lists the active storages that could hold the missing content type and enables it on the one you pick.

Order of workCopy Anchor Link

1. Check that this host's pve-container can set up the requested OS release.
2. Build the network string, the feature list and the pct create options.
3. Validate the settings.
4. Select and validate the template storage and the container storage.
5. Find the template, download it if needed.
6. Run pct create.
7. Add passthrough entries to the container config.
8. Start the container and wait for an address.
9. Prepare the system inside (locale, time zone, base packages).
10. Fetch install/<app>-install.sh and run it inside the container.
11. On failure: collect the logs, explain, and ask what to do with the container.

OS release supportCopy Anchor Link

A pve-container package that is older than the OS release cannot configure it, and pct create would fail after the download. lxc_os_support_check asks the host first, for Debian and Ubuntu. If the release is not supported it prints

pve-container <version> on this host cannot create Debian 13 containers.

and, when interactive, offers Update the LXC stack to pve-container <version> (apt dist-upgrade), Use Debian <older> instead (not every app supports it) or Cancel. Unattended, or when neither option exists, it prints what to do and exits with 231.

From settings to pct createCopy Anchor Link

The call has the form pct create <CTID> <template storage>:vztmpl/<template> <options>. It runs with umask 022, so that a restrictive umask in the operator's shell does not produce a container whose /etc other users cannot enter.

For openeuler, rockylinux, almalinux and amazonlinux the backend adds -ostype centos, because Proxmox VE cannot derive a usable OS type for them.

Where each setting comes from, and the precedence between command line, saved defaults and the wizard, is covered in Settings and the wizard and the Configuration reference.

ValidationCopy Anchor Link

validate_ct_settings checks the values pct create would reject, wherever they came from: memory, root password length, container ID, cores, disk size, IPv4 address, gateway, DNS servers, search domain and mount types. Problems are listed under These settings would be rejected by pct create: and the run ends with exit code 208. A common one is a memory value given in GB:

RAM 4 MiB is too little (var_ram is in MiB; 4 GiB would be 4096)

FeaturesCopy Anchor Link

The -features option is assembled from the settings.

TUN, needed by VPN applications such as WireGuard, OpenVPN and Tailscale, is not a Proxmox feature flag. With var_tun=yes the backend appends two lines to /etc/pve/lxc/<CTID>.conf after creation:

lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file

StorageCopy Anchor Link

Two storages are needed: one for the template (vztmpl) and one for the root disk (rootdir). They are taken from var_template_storage and var_container_storage when those are set and valid. Otherwise a storage is chosen automatically if only one qualifies, and a Storage Pools dialog asks if there are several.

The container storage is then validated:

A storage that is 85 % full or more produces a warning. At 95 % an interactive run asks Continue anyway?, and at 98 % an unattended run refuses with exit code 214.

TemplatesCopy Anchor Link

SearchCopy Anchor Link

The template name is searched as <os>-<version>, for example debian-13, restricted to the host's architecture. Debian and Ubuntu use the -standard_ templates; Alpine, Fedora, Rocky and CentOS the -default_ ones.

1. Already downloaded. If the template storage holds a matching template, the newest one is used and the catalog is not contacted.
2. Proxmox catalog. Otherwise pveam update refreshes the catalog (with a 30-second limit) and the newest matching entry of pveam available -section system is taken.
3. linuxcontainers.org. If Proxmox offers nothing for this OS, version and architecture, the image catalog at images.linuxcontainers.org is searched, see below.

If the version does not exist in the catalog, the wizard has usually already handled it: resolve_os_version proposes the closest available version in an OS VERSION NOT AVAILABLE dialog, or switches to it with a warning when unattended. If the search still ends without a template, an interactive run lists the versions the host does offer, and an unattended run stops with No standard_ template found for debian 14 and exit code 225.

DownloadCopy Anchor Link

pveam download <storage> <template> is tried up to three times, waiting 5 and then 10 seconds in between. Success is judged by the template appearing in pveam list, not by the exit code. If the catalog names a template the server no longer has, the catalog is refreshed and the current file is taken.

After the third failure the backend prints Template download failed after 3 attempts: <template>, the last relevant line from pveam, and the most likely cause it can determine: no space on the storage, the HTTP proxy from Datacenter → Options, a host that cannot resolve download.proxmox.com, or a host that cannot reach it. Exit code 222. If the template is still missing from the storage afterwards, exit code 223.

A template on disk is checked before use. A file smaller than 1 MB or one that tar cannot list is downloaded again.

Two runs that need the same template wait for each other through a lock file /tmp/template.<template>.lock. After ten waits of 30 seconds the run gives up with exit code 211.

The linuxcontainers.org fallbackCopy Anchor Link

When Proxmox has no template the backend prints

No Proxmox template for <os> <version> on <arch>, trying linuxcontainers.org

and reads https://images.linuxcontainers.org/streams/v1/images.json. It needs jq on the host and installs it if missing. The newest build of the matching release is downloaded into the template storage as <os>-<release>-<arch>-rootfs.tar.xz and reused on later runs.

• The release is matched by name or by the image's aliases. archlinux with version base maps to current, Devuan 5 to daedalus, and CentOS 10 to 10-Stream.
• Images published only as squashfs are unpacked and repacked as a tarball. This installs squashfs-tools on the host.
• Images without /etc/network get an empty /etc/network/interfaces added, because Proxmox VE expects the directory.
• If the catalog cannot be reached or has no such image, a warning is printed and the normal Proxmox search continues, so the error you finally see is about what this host offers.

This is how distributions Proxmox does not ship as templates can be created at all.

arm64Copy Anchor Link

Proxmox VE on arm64 is supported. The differences on such a host:

• arch_check looks at the script's var_arm64. yes continues, no stops with exit code 106, and an unset value asks whether to try. A notice ARM64 support is in active development. is shown before the menu.
• Templates are filtered by architecture. Where the Proxmox catalog has no arm64 template, the image comes from linuxcontainers.org as described above.
• The base packages installed on Debian and Ubuntu additionally include openssh-server, wget and gcc.
• Install scripts choose release assets with arch_resolve, see Install scripts.

When pct create failsCopy Anchor Link

The output of pct create goes to /tmp/pct_create_<CTID>_<timestamp>_<SESSION_ID>.log and is appended to the build log. The backend reads it to decide what to do.

After a successful create the backend waits up to 10 seconds for the ID to appear in pct list (exit code 215 otherwise) and checks that the config has a rootfs line (216).

PassthroughCopy Anchor Link

Passthrough entries are appended to /etc/pve/lxc/<CTID>.conf between creation and first start.

USBCopy Anchor Link

For a privileged container (var_unprivileged=0) USB serial passthrough is configured automatically: all devices are allowed (lxc.cgroup2.devices.allow: a), the capability drop list is cleared (lxc.cap.drop:), character devices 188 and 189 are allowed explicitly, and /dev/serial/by-id, /dev/ttyUSB0, /dev/ttyUSB1, /dev/ttyACM0 and /dev/ttyACM1 are bind-mounted when present. Unprivileged containers get none of this.

GPUCopy Anchor Link

With var_gpu=yes the backend looks for GPUs on the host:

• One GPU type is configured without a question. With several, a prompt Select GPU type(s) appears; no answer within 60 seconds means all of them. A host with several NVIDIA cards gets a second prompt to choose cards.
• Each node becomes a dev<N>: <node>,gid=<gid> line, a format the Proxmox VE interface displays as well.
• After the first start the backend reads the video and render group IDs inside the container (creating the groups if needed), stops the container, writes the correct IDs into the dev<N> lines and starts it again.
• For an AMD GPU the root disk is grown by 4 GB to make room for ROCm.
• NVIDIA needs the host driver loaded. Otherwise the backend prints NVIDIA GPU detected via PCI but no /dev/nvidia* devices found and skips it. The matching driver libraries inside the container are the install script's job.
• If the host has no GPU device at all, the summary says GPU Passthrough: Requested - no GPU devices on this host and the install goes on without it.

Other devicesCopy Anchor Link

• var_tun=yes: the TUN lines shown under Features.
• A Coral TPU at /dev/apex_0 on the host is detected and bind-mounted into every container the scripts create.

Start and networkCopy Anchor Link

pct start is checked. If the container does not start, the backend prints Container <CTID> was created but would not start, the relevant lines from journalctl -u pve-container@<CTID>, and a hint for a foreground start with lxc-start; exit code 227. If it is not in state running within 10 seconds: exit code 117.

Then the backend waits for an address on eth0, IPv4 first, then a global IPv6 address. It polls 60 times with growing pauses, about two minutes in total. If nothing arrives:

No IP assigned to CT <CTID> after 60 attempts

with a checklist (bridge, DHCP server, static configuration, firewall, Tailscale MagicDNS) and exit code 118.

With an address, a connectivity test follows: ping to 1.1.1.1 and 8.8.8.8, IPv6 ping, and a TCP connection to 1.1.1.1:443. A failed test is only a warning, Network configured (IP: <ip>) but connectivity test failed - installation will continue, because ICMP is often filtered where HTTPS works.

Alpine containers skip this wait and go straight to the package step.

Preparing the systemCopy Anchor Link

Under the message Customizing container the backend runs a few commands inside the container with pct exec:

• var_http_proxy set: writes /etc/profile.d/90-http-proxy.sh and an APT proxy file.
• var_inherit_host_ca=yes: copies the host's /usr/local/share/ca-certificates/*.crt into the container and updates its trust store.
• Debian, Ubuntu, Devuan: generates the locale, sets the time zone, and installs sudo curl mc gnupg2 jq. If deb.debian.org or archive.ubuntu.com does not resolve, public DNS servers are written to /etc/resolv.conf first. If apt-get update fails, other mirrors are probed in three phases; when all fail you are asked for a mirror host name.
• Alpine: sets the latest-stable repositories and installs bash newt curl openssh nano mc ncurses jq, with a mirror fallback.
• Fedora, Rocky, AlmaLinux, CentOS, openEuler, openSUSE, Arch, Gentoo and others: sets the time zone, fixes the console terminal type, and makes sure curl is installed.

If the container disappears during this step the backend says so instead of blaming the package manager: Container <CTID> was stopped during its setup (<task> by <user>) with exit code 143, or Container <CTID> stopped by itself during its setup with 199.

Handing over to the install scriptCopy Anchor Link

The install script is fetched on the host, from a local checkout if there is one, otherwise from the script repository. A failure here is reported as Could not fetch install/<app>-install.sh with exit code 115, and a hint to set COMMUNITY_SCRIPTS_URL when running a fork.

The backend exports what the script needs, among them:

The script is then run with lxc-attach -n <CTID> -- bash -c "<script>". From here on the terminal shows the install script's output; see Install scripts.

Inside the container the run leaves small files the host reads afterwards:

If the console is closedCopy Anchor Link

Closing the browser tab or the SSH session does not abort the install. The script inside the container ignores the hangup and continues. The host process redirects its output to the build log and checks every 15 seconds, for up to six hours, for the .done or .failed file. Ctrl-C is different: it stops the container and ends the run with exit code 130. The container is not removed.

If the install fails after the console was closed, nobody can answer the question below, so the container is kept.

When the install failsCopy Anchor Link

The host prints Installation failed in container <CTID> (exit code: <n>), builds a combined log from the host's build log and the container's install log, and prints its path:

Installation log: /tmp/<app>-<CTID>-<SESSION_ID>.log

It then explains the exit code and looks at the output of the failed step to classify the problem. Depending on the result, extra choices appear in the menu:

What would you like to do?

  1) Remove container and exit
  2) Keep container for debugging
  3) Retry with verbose mode (full rebuild)
  4) Repair APT/DPKG state and re-run install (in-place)
  5) Retry with more resources (RAM: 2048→4096 MiB, CPU: 2→4 cores)

Select option [1-5] (default: 1, auto-remove in 60s):

How the answer is read matters:

• Enter without input selects option 1.
• No answer within 60 seconds removes the container.
• An answer that is not one of the offered numbers keeps the container.
• If the answer cannot be read at all, the container is kept and Remove it manually if not needed: pct destroy <CTID> is printed.
• With dev_mode=keep the question is skipped and the container kept. With dev_mode=breakpoint a shell in the container opens first. See Dev mode.

The run then ends with the install script's exit code.

A failure on the host after the container was created, for example while the network was being awaited, goes through the general error handler instead. It prints the error line and the log path and asks Remove broken container <CTID>? (Y/n) [auto-remove in 60s]:. This prompt only ever refers to the container the current run created.

After a successful installCopy Anchor Link

description writes the container notes shown in the Proxmox VE interface, runs the var_post_install hook on the host if one is configured (its output goes to /var/log/community-scripts/post-install-<CTID>.log), and reports the run as finished. The container script then prints the address of the application.