podman-update(1)

📦

version 6.1.4 · 19 versions

🫶 `podman-update(1)` 🫶

okay so this is the General Commands Manual page for podman-update(1), and it’s lowkey iconic because it’s all about changing a container’s config after it already exists. no cap, we’re keeping every flag. 💖

🌸 NAME 🌸

podman-update — Update the configuration of a given container. periodt. ✨

🦋 SYNOPSIS 🦋

podman update [options] container

podman container update [options] container

✨ DESCRIPTION ✨

Updates the configuration of an existing container, allowing changes to resource limits and healthchecks. it’s giving “glow-up for a container that’s already on the scene,” bestie. 💅

💅 OPTIONS 💅

okay bestie, buckle up — every single option is here, in order, no skipping. 🎀

🎀 `--blkio-weight=weight` 🎀

Block IO relative weight. The weight is a value between 10 and 1000.

This option is not supported on cgroups V1 rootless systems. 💀

🎀 `--blkio-weight-device=device:weight` 🎀

Block IO relative device weight. that’s it, that’s the whole vibe. ✨

🎀 `--cpu-period=limit` 🎀

Set the CPU period for the Completely Fair Scheduler (CFS), which is a duration in microseconds. Once the container’s CPU quota is used up, it will not be scheduled to run until the current period ends. Defaults to 100000 microseconds.

On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error.

This option is not supported on cgroups V1 rootless systems.

🎀 `--cpu-quota=limit` 🎀

Limit the CPU Completely Fair Scheduler (CFS) quota.

Limit the container’s CPU usage. By default, containers run with the full CPU resource. The limit is a number in microseconds. If a number is provided, the container is allowed to use that much CPU time until the CPU period ends (controllable via --cpu-period).

This option is not supported on cgroups V1 rootless systems.

🎀 `--cpu-rt-period=microseconds` 🎀

Limit the CPU real-time period in microseconds.

Limit the container’s Real Time CPU usage. This option tells the kernel to restrict the container’s Real Time CPU usage to the period specified.

This option is only supported on cgroups V1 rootful systems.

🎀 `--cpu-rt-runtime=microseconds` 🎀

Limit the CPU real-time runtime in microseconds.

Limit the containers Real Time CPU usage. This option tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: Period of 1,000,000us and Runtime of 950,000us means that this container can consume 95% of available CPU and leave the remaining 5% to normal priority tasks.

The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup.

This option is only supported on cgroups V1 rootful systems.

🎀 `--cpu-shares`, `-c=shares` 🎀

CPU shares (relative weight).

By default, all containers get the same proportion of CPU cycles. This proportion can be modified by changing the container’s CPU share weighting relative to the combined weight of all the running containers. Default weight is 1024.

The proportion only applies when CPU-intensive processes are running. When tasks in one container are idle, other containers can use the leftover CPU time. The actual amount of CPU time varies depending on the number of containers running on the system.

For example, consider three containers, one has a cpu-share of 1024 and two others have a cpu-share setting of 512. When processes in all three containers attempt to use 100% of CPU, the first container receives 50% of the total CPU time. If a fourth container is added with a cpu-share of 1024, the first container only gets 33% of the CPU. The remaining containers receive 16.5%, 16.5% and 33% of the CPU.

On a multi-core system, the shares of CPU time are distributed over all CPU cores. Even if a container is limited to less than 100% of CPU time, it can use 100% of each individual CPU core.

For example, consider a system with more than three cores. If the container C0 is started with --cpu-shares=512 running one process, and another container C1 with --cpu-shares=1024 running two processes, this can result in the following division of CPU shares:

PID 100, container C0, CPU 0, CPU share 100% of CPU0
PID 101, container C1, CPU 1, CPU share 100% of CPU1
PID 102, container C1, CPU 2, CPU share 100% of CPU2

This option is not supported on cgroups V1 rootless systems.

🎀 `--cpus=number` 🎀

Number of CPUs. The default is 0.0 which means no limit. This is shorthand for --cpu-period and --cpu-quota, therefore the option cannot be specified with --cpu-period or --cpu-quota.

On some systems, changing the CPU limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error.

This option is not supported on cgroups V1 rootless systems.

🎀 `--cpuset-cpus=number` 🎀

CPUs in which to allow execution. Can be specified as a comma-separated list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof (e.g. 0-3,7,11-15).

This option is not supported on cgroups V1 rootless systems.

🎀 `--cpuset-mems=nodes` 🎀

Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.

If there are four memory nodes on the system (0-3), use --cpuset-mems=0,1 then processes in the container only uses memory from the first two memory nodes.

This option is not supported on cgroups V1 rootless systems.

🎀 `--device-read-bps=path:rate` 🎀

Limit read rate (in bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb).

This option is not supported on cgroups V1 rootless systems.

🎀 `--device-read-iops=path:rate` 🎀

Limit read rate (in IO operations per second) from a device (e.g. --device-read-iops=/dev/sda:1000).

This option is not supported on cgroups V1 rootless systems.

🎀 `--device-write-bps=path:rate` 🎀

Limit write rate (in bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb).

This option is not supported on cgroups V1 rootless systems.

🎀 `--device-write-iops=path:rate` 🎀

Limit write rate (in IO operations per second) to a device (e.g. --device-write-iops=/dev/sda:1000).

This option is not supported on cgroups V1 rootless systems.

🎀 `--env`, `-e=env` 🎀

Add a value (e.g. env=value) to the container. Can be used multiple times. If the value already exists in the container, it is overridden. To remove an environment variable from the container, use the --unsetenv option.

Note that the env updates only affect the main container process after the next start. 🫶

🎀 `--health-cmd="command" | '["command", arg1 , ...]'` 🎀

Set or alter a healthcheck command for a container. The command is a command to be executed inside the container that determines the container health. The command is required for other healthcheck options to be applied. A value of none disables existing healthchecks.

Multiple options can be passed in the form of a JSON array; otherwise, the command is interpreted as an argument to /bin/sh -c.

Note: The default values are used even if healthcheck is configured in the image. 👑

🎀 `--health-interval=interval` 🎀

Set an interval for the healthchecks. An interval of disable results in no automatic timer setup. The default is 30s.

Note: This parameter will overwrite related healthcheck configuration from the image.

Changing this setting resets the timer. ⏰

🎀 `--health-log-destination=directory_path` 🎀

Set the destination of the HealthCheck log. Directory path, local or events_logger (local use container state file) (Default: local)

local: (default) HealthCheck logs are stored in overlay containers. (For example: $runroot/healthcheck.log)
directory: creates a log file named <container-ID>-healthcheck.log with HealthCheck logs in the specified directory.
events_logger: The log will be written with logging mechanism set by events_logger. It also saves the log to a default directory, for performance on a system with a large number of logs.

Warning: Changing this setting may cause the loss of previous logs. 😭

🎀 `--health-max-log-count=number of stored logs` 🎀

Set maximum number of attempts in the HealthCheck log file. ('0' value means an infinite number of attempts in the log file) (Default: 5 attempts)

🎀 `--health-max-log-size=size of stored logs` 🎀

Set maximum length in characters of stored HealthCheck log. ("0" value means an infinite log length) (Default: 500 characters)

--health-on-failure=action — what should podman do when your container goes from healthy to unhealthy? 💀 The default is none.
- none: do nothing. just vibe. take no action.
- kill: kill the container. bye 👋
- restart: restart the container. but do not combine the restart action with the --restart flag — that's giving messy. if you're running inside of a systemd unit, consider using the kill or stop action instead, so you can make use of systemd's restart policy.
- stop: stop the container.
--health-retries=retries — how many retries are allowed before a healthcheck is considered unhealthy. default is 3.

Note: this parameter can overwrite the healthcheck configuration from the image. 🫶

--health-start-period=period — the initialization time a container needs to bootstrap. value can be expressed in time format like 2m3s. default value is 0s.

Note: the health check command is executed as soon as a container is started. if the health check is successful, the container's health state gets updated to healthy. however, if the health check fails, the health state stays as starting until either the health check is successful or until the --health-start-period time is over. if the health check command fails after the --health-start-period time is over, the health state gets updated to unhealthy. the health check command is executed periodically based on the value of --health-interval.

Note: this parameter will overwrite related healthcheck configuration from the image. 😭

--health-startup-cmd="command" | '["command", arg1 , ...]' — set a startup healthcheck command for a container. this command is executed inside the container and it's used to gate the regular healthcheck. when the startup command succeeds, the regular healthcheck begins and the startup healthcheck ceases. optionally, if the command fails a set number of times, the container is restarted. a startup healthcheck can be used to ensure that containers with an extended startup period are not marked as unhealthy until they're fully started. startup healthchecks can only be used when a regular healthcheck (from the container's image or the --health-cmd option) is also set. ✨
--health-startup-interval=interval — set an interval for the startup healthcheck. an interval of disable results in no automatic timer setup. default is 30s.

changing this setting resets the timer, depending on the state of the container. 🎀

--health-startup-retries=retries — the number of attempts allowed before the startup healthcheck restarts the container. if set to 0, the container is never restarted. default is 0.
--health-startup-success=retries — the number of successful runs required before the startup healthcheck succeeds and the regular healthcheck begins. a value of 0 means that any success begins the regular healthcheck. default is 0. 💅
--health-startup-timeout=timeout — the maximum time a startup healthcheck command has to complete before it's marked as failed. value can be expressed in a time format like 2m3s. default value is 30s.
--health-timeout=timeout — the maximum time allowed to complete the healthcheck before an interval is considered failed. like start-period, the value can be expressed in a time format such as 1m22s. default value is 30s.

Note: a timeout marks the healthcheck as failed. if the healthcheck command itself runs longer than the specified timeout, it will be sent a SIGKILL signal. 💀

Note: this parameter will overwrite related healthcheck configuration from the image.

--latest, -l — instead of providing the container name or ID, just use the last created container. note: the last started container can be from other users of Podman on the host machine. (this option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) 🙈
--memory, -m=number[unit] — memory limit. a unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).

allows the memory available to a container to be constrained. if the host supports swap memory, then the --memory memory setting can be larger than physical RAM. if a limit of 0 is specified (not using --memory), the container's memory is not limited. the actual limit may be rounded up to a multiple of the operating system's page size (the value is very large, that's millions of trillions 😭).

this option is not supported on cgroups V1 rootless systems.

--memory-reservation=number[unit] — memory soft limit. a unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).

after setting memory reservation, when the system detects memory contention or low memory, containers are forced to restrict their consumption to their reservation. so always set the value below --memory, otherwise the hard limit takes precedence. by default, memory reservation is the same as memory limit.

this option is not supported on cgroups V1 rootless systems.

--memory-swap=number[unit] — a limit value equal to memory plus swap. a unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).

must be used with the -m (--memory) flag. the argument value must be larger than that of -m (--memory). by default, it's set to double the value of --memory. 🔥

set number to -1 to enable unlimited swap.

this option is not supported on cgroups V1 rootless systems.

--memory-swappiness=number — tune a container's memory swappiness behavior. accepts an integer between 0 and 100.

this flag is only supported on cgroups V1 rootful systems. 🥲

--no-healthcheck — disable any defined healthchecks for the container. periodt.
--pids-limit=limit — tune the container's pids limit. set to -1 to have unlimited pids for the container. default is 2048 on systems that support the "pids" cgroup controller.
--restart=policy — restart policy to follow when containers exit. restart policy does not take effect if a container is stopped via the podman kill or podman stop commands.

valid policy values are:

no : do not restart containers on exit
never : synonym for no; do not restart containers on exit
on-failure[:max_retries] : restart containers when they exit with a non-zero exit code, retrying indefinitely or until the optional max_retries count is hit
always : restart containers when they exit, regardless of status, retrying indefinitely
unless-stopped : restart containers when they exit, unless the container was explicitly stopped by the user. after a system reboot, containers with this policy will be restarted by podman-restart.service only if they were not explicitly stopped by the user before the reboot. this differs from always, which restarts containers after a system reboot regardless of whether they were user-stopped 👑

Podman provides a systemd unit file, podman-restart.service, which restarts containers after a system reboot.

when running containers in systemd services, use the restart functionality provided by systemd. in other words, do not use this option in a container unit — instead set the Restart= systemd directive in the [Service] section. see podman-systemd.unit(5) and systemd.service(5).

--ulimit=option — ulimit options. sets the ulimits values inside of the container.

--ulimit with a soft and hard limit in the format <type>=<soft>:<hard>. for example:

$ podman run --ulimit nofile=1024:1024 --rm ubi9 ulimit -n 1024

set -1 for the soft or hard limit to set the limit to the maximum limit of the current process. in rootful mode this is often unlimited.

if nofile and nproc are unset, a default value of 1048576 will be used, unless overridden in containers.conf(5). however, if the default value exceeds the hard limit for the current rootless user, the current hard limit will be applied instead. 🧚

use host to copy the current configuration from the host.

don't use nproc with the ulimit flag, because Linux uses nproc to set the maximum number of processes available to a user, not to a container.

use the --pids-limit option to modify the cgroup control to limit the number of processes within a container.

Note: ulimit changes apply after container restart. 🔁

--unsetenv=env — unset environment variables from the container.

note that the env updates only affect the main container process after the next start.

🌈 EXAMPLES 🌈

update a container with a new cpu quota and period:

podman update --cpus=0.5 ctrID

update the latest container with a new cpu value:

podman update --latest --cpus=1

update a container's ulimit:

podman update --ulimit nofile=1024:1024 ctrID

update a container with multiple options at ones:

podman update --cpus 5 --cpuset-cpus 0 --cpu-shares 123 --cpuset-mems 0 \
  --memory 1G --memory-swap 2G --memory-reservation 2G \
  --blkio-weight-device /dev/sda:123 --blkio-weight 123 \
  --device-read-bps /dev/sda:10mb --device-write-bps /dev/sda:10mb \
  --device-read-iops /dev/sda:1000 --device-write-iops /dev/sda:1000 \
  --pids-limit 123 ctrID

🦋 HISTORY 🦋

June 2025, Latest option added by Hayato Kihara kai.21banana@gmail.com ⟨mailto:kai.21banana@gmail.com⟩ August 2022, Originally written by Charlie Doern cdoern@redhat.com ⟨mailto:cdoern@redhat.com⟩

and that's the whole page bestie, you ate that 💅✨ this lil gem is podman-update(1) from the Podman source — go be iconic with it 🎀🫶

📦 where this page comes from

arch rolling: podman-docker 6.1.4-1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

podman-update(1)

🫶 podman-update(1) 🫶

🌸 NAME 🌸

🦋 SYNOPSIS 🦋

✨ DESCRIPTION ✨

💅 OPTIONS 💅

🎀 --blkio-weight=weight 🎀

🎀 --blkio-weight-device=device:weight 🎀

🎀 --cpu-period=limit 🎀

🎀 --cpu-quota=limit 🎀

🎀 --cpu-rt-period=microseconds 🎀

🎀 --cpu-rt-runtime=microseconds 🎀

🎀 --cpu-shares, -c=shares 🎀

🎀 --cpus=number 🎀

🎀 --cpuset-cpus=number 🎀

🎀 --cpuset-mems=nodes 🎀

🎀 --device-read-bps=path:rate 🎀

🎀 --device-read-iops=path:rate 🎀

🎀 --device-write-bps=path:rate 🎀

🎀 --device-write-iops=path:rate 🎀

🎀 --env, -e=env 🎀

🎀 --health-cmd="command" | '["command", arg1 , ...]' 🎀

🎀 --health-interval=interval 🎀

🎀 --health-log-destination=directory_path 🎀

🎀 --health-max-log-count=number of stored logs 🎀

🎀 --health-max-log-size=size of stored logs 🎀

🌈 EXAMPLES 🌈

💜 SEE ALSO 💜

🦋 HISTORY 🦋

🫶 `podman-update(1)` 🫶

🎀 `--blkio-weight=weight` 🎀

🎀 `--blkio-weight-device=device:weight` 🎀

🎀 `--cpu-period=limit` 🎀

🎀 `--cpu-quota=limit` 🎀

🎀 `--cpu-rt-period=microseconds` 🎀

🎀 `--cpu-rt-runtime=microseconds` 🎀

🎀 `--cpu-shares`, `-c=shares` 🎀

🎀 `--cpus=number` 🎀

🎀 `--cpuset-cpus=number` 🎀

🎀 `--cpuset-mems=nodes` 🎀

🎀 `--device-read-bps=path:rate` 🎀

🎀 `--device-read-iops=path:rate` 🎀

🎀 `--device-write-bps=path:rate` 🎀

🎀 `--device-write-iops=path:rate` 🎀

🎀 `--env`, `-e=env` 🎀

🎀 `--health-cmd="command" | '["command", arg1 , ...]'` 🎀

🎀 `--health-interval=interval` 🎀

🎀 `--health-log-destination=directory_path` 🎀

🎀 `--health-max-log-count=number of stored logs` 🎀

🎀 `--health-max-log-size=size of stored logs` 🎀