pct-create

Create a container from a template with 4GB size, give it 512MiB of memory and unlimited access to CPU

$ pct [[cr|create]] [100] [local:vztmpl/distro-name.tar.zst] --rootfs [local-lvm]:4

$ pct [[cr|create]] [100] [local:vztmpl/distro-name.tar.zst] --rootfs [local-lvm]:[4] --memory [8192]

$ pct [[cr|create]] [100] [local:vztmpl/distro-name.tar.zst] --rootfs [local-lvm]:[4] --hostname [hostname] --password [password]

$ pct [[cr|create]] [100] [local:vztmpl/distro-name.tar.zst] --rootfs [local-lvm]:[4] --net0 name=[eth0],bridge=[vmbr0],ip=[dhcp|manual|10.0.0.1/24] --features nesting=1

$ pct [[cr|create]] [100] [local:vztmpl/distro-name.tar.zst] --rootfs [local-lvm]:[4] --start

pct create <vmid> <template> [options]

<vmid>
    The unique ID (Virtual Machine ID) for the new container. Must be an integer and not currently in use by another VM or container.

<template>
    The path or ID of the LXC template file (e.g., local:vztmpl/debian-11-standard_11.0-1_amd64.tar.gz). Templates can be downloaded using pveam.

--arch <architecture>
    Container architecture (e.g., amd64, arm64). Defaults to host architecture.

--cores <integer>
    Number of CPU cores allocated to the container.

--cpuunits <integer>
    CPU weight for fairness scheduling (higher value means more CPU time, default is 1024).

--memory <integer>
    RAM in MB allocated to the container.

--swap <integer>
    Swap space in MB allocated to the container.

--rootfs <volume>
    Disk volume for the container's root filesystem (e.g., local-lvm:4G or local-zfs:pool/subvol,size=8G). Specifies storage and size.

--storage <storage_id>
    The storage where the rootfs will be created if not explicitly specified in --rootfs. For example, local-lvm.

--hostname <string>
    Hostname for the container.

--net<n> <string>
    Network device configuration. Multiple devices can be specified (e.g., --net0 name=eth0,bridge=vmbr0,ip=dhcp).
Use ip for static IP, ip=dhcp for DHCP.

--password <string>
    Password for the root user inside the container.

--unprivileged <0|1>
    Create an unprivileged container (1 for yes, 0 for no). Defaults to 0 (privileged).

--ostype <string>
    Operating system type (e.g., debian, ubuntu, centos). Automatically detected from template if not specified.

--onboot <0|1>
    Start the container automatically on host boot (1 for yes, 0 for no).

--start <0|1>
    Start the container immediately after creation (1 for yes, 0 for no). Defaults to 0.

--description <string>
    A descriptive note for the container.

--ip<n> <string>
    IP address(es) for network device n. Can be dhcp or <IP>/<CIDR> (e.g., 192.168.1.10/24). Requires --net<n> to be defined.

--gw <IP>
    Default gateway IP address. Typically used with static IP configurations.

--nameserver <IP>[,<IP>...]
    Comma-separated list of DNS server IP addresses.

--searchdomain <string>
    DNS search domain.

--ssh-public-keys <path>
    Path to a file containing SSH public keys to add to the root user's authorized_keys inside the container for remote access.

--tags <string>
    Comma-separated list of tags for the container, used for organization and filtering.

The pct create command is a fundamental utility within the Proxmox Virtual Environment (PVE) for deploying Linux Containers (LXC). It enables users to quickly provision new lightweight virtualized environments based on pre-downloaded OS templates. Unlike full virtualization (like KVM), LXC containers share the host kernel, resulting in lower overhead and faster startup times, making them ideal for microservices, application hosting, and testing environments.

This command allows for extensive customization during container creation, including defining the container's unique ID (VMID), selecting the operating system template, allocating CPU cores and memory, configuring network interfaces (IP addresses, gateways, DNS), setting up storage for the root filesystem, and specifying various other operational parameters like hostname, startup behavior, and security features. By leveraging templates, pct create simplifies the deployment process, allowing for consistent and repeatable container setups across a Proxmox cluster.

Creating LXC containers requires sufficient system resources (CPU, RAM, storage) on the Proxmox host. VMIDs must be unique across all VMs and containers on the cluster. Network configurations need to be carefully planned to avoid IP conflicts. Unprivileged containers offer enhanced security by preventing root in the container from gaining root on the host, but they may have limitations with certain advanced features or mounting specific types of filesystems without additional configuration.

Before creating a container, you typically need an LXC template. These templates are pre-built root filesystems for various operating systems (e.g., Debian, Ubuntu, CentOS) and are usually downloaded from Proxmox's template repositories using the pveam download command (e.g., pveam download local debian-11-standard_11.0-1_amd64.tar.gz). The <template> argument in pct create refers to the path of this downloaded template on a storage identified by Proxmox.

By default, pct create generates a 'privileged' container (--unprivileged 0). In a privileged container, the root user inside the container is also root on the host, which poses a security risk. 'Unprivileged' containers (--unprivileged 1) map the container's root user to an unprivileged user on the host, significantly enhancing security. While unprivileged containers are recommended for production, they might require specific configurations for certain operations (e.g., mounting NFS shares, running Docker) due to stricter permission management.

pct create allows precise allocation of resources like CPU cores, memory, and disk space. It's crucial to set these limits appropriately to prevent a single container from monopolizing host resources and affecting other VMs/containers. Proxmox uses cgroups to enforce these limits. For disk, --rootfs allows specifying the storage pool and size, while --storage can be used to just pick a storage pool for the default size, enabling flexible storage management.

The pct command is an integral part of Proxmox Virtual Environment, which has been under active development since its initial release in 2007. Proxmox VE introduced LXC container support as a lightweight virtualization alternative to KVM virtual machines, leveraging Linux container technology for efficient resource utilization. The pct command-line tool was developed to provide a comprehensive and user-friendly interface for managing these LXC containers, mirroring the functionality available through the Proxmox web GUI. Its evolution has focused on integrating new LXC features, improving resource management, and enhancing security aspects like unprivileged containers.

pct(1), pct start(1), pct stop(1), pct destroy(1), pct list(1), pveam(1), lxc(7), pve-container(1)