Safely Take CPUs Online or Offline with chcpu

You will finish with a safe way to inspect CPU availability, choose the right chcpu operation, and verify a planned online or offline change. The installed Ubuntu package is util-linux 2.39.3-9ubuntu6.6, while this shell resolves chcpu to a separate util-linux 2.41.3 binary. Allow about fifteen minutes for a read-only check, or longer if you are scheduling a change on a production host.

You need a shell, chcpu, lscpu, and a maintenance plan. Reading the current state is normally unprivileged. Enabling, disabling, configuring, deconfiguring, and rescanning CPUs can require root and can affect running workloads, interrupt placement, capacity and service performance.

1. Check the installed command

Start by confirming which executable and version you will use. This is a read-only step:

$ command -v chcpu
/home/linuxbrew/.linuxbrew/sbin/chcpu
$ chcpu --version
chcpu from util-linux 2.41.3

On this machine the command found in the shell differs from the packaged manpage because another installation is earlier in PATH. That matters: the local manpage describes the distro package, while a different binary may support a different option set. Run chcpu --help as a second check:

$ chcpu --help
Usage: chcpu [options]
Configure CPUs in a multi-processor system.

Checkpoint: if your path or version differs, use the matching manpage before changing CPU state. For the distro binary, call it by its full path or adjust PATH deliberately rather than assuming the two installations are interchangeable.

2. Record the current CPU state

Use lscpu before planning a change. It reports the number of CPUs and the online CPU list without changing anything:

$ lscpu | grep -E '^(CPU\(s\)|On-line CPU\(s\) list:)'
CPU(s):                                  8
On-line CPU(s) list:                     0-7

Your numbers will differ. Keep the output with the maintenance record, including the CPU list you intend to change. A CPU address is the number used in a cpu-list, not a core number or a processor model number. Lists may contain individual addresses and ranges, such as 0,5,7,9-11.

For a closer look at online state, read the kernel's per-CPU files. CPU 0 normally has no online file because it is the boot CPU:

$ for f in /sys/devices/system/cpu/cpu*/online; do
>     printf '%s: ' "$f"
>     cat "$f"
> done
/sys/devices/system/cpu/cpu1/online: 1
/sys/devices/system/cpu/cpu2/online: 1
# remaining lines are host-specific

A value of 1 means online and 0 means offline. This is a verification aid, not a reason to write directly to sysfs. Let chcpu perform the requested operation so its exit status and diagnostics are visible.

3. Choose online or offline deliberately

chcpu --disable CPU_LIST asks the kernel to set the selected CPUs offline. The matching recovery operation is chcpu --enable CPU_LIST, which brings them online again. A CPU must be configured before it can be enabled.

Disabling CPUs is service-disrupting. Do not use a production CPU list copied from another host, and do not include CPU 0 merely because it is the first number. Check scheduler capacity, CPU affinity, interrupt assignments and application requirements first. Keep at least the capacity your workload needs.

When you have a reviewed maintenance window and a specific list, the command shape is:

$ sudo chcpu --disable CPU_LIST
$ printf 'chcpu exit status: %s\n' "$?"
chcpu exit status: 0

Replace CPU_LIST with an explicit value such as 6 or 6,7. Do not paste the placeholder. A status of 0 means success; status 1 means failure; status 64 means partial success. A partial result requires you to inspect the state again before retrying.

Undo a successful offline operation with the reviewed list:

$ sudo chcpu --enable CPU_LIST
$ lscpu | grep -E '^(CPU\(s\)|On-line CPU\(s\) list:)'

If enabling fails, check whether the CPUs are configured and whether the host or hypervisor permits them to be enabled. Do not repeatedly retry a failed state transition while a workload is under pressure.

4. Understand configure and deconfigure

--configure and --deconfigure are different from online and offline. They apply to virtual hardware managed by a hypervisor. Configuring takes CPUs from the hypervisor CPU pool and assigns them to the virtual machine. Deconfiguring returns them to that pool.

A CPU must be offline before it can be deconfigured. That gives the normal removal sequence two separate stages:

1. Disable the CPU with sudo chcpu --disable CPU_LIST and verify that it is offline.
2. Only after the hypervisor and workload plan permit removal, run sudo chcpu --deconfigure CPU_LIST.

Deconfiguration can reduce the virtual machine's available hardware and may be difficult to reverse without hypervisor access. Treat it as a capacity change, not as a faster form of offline operation. On systems without CPU hot-plug support, either operation may fail. On IBM z/VM, the upstream manual says deconfigure is not supported because CPUs remain configured.

5. Rescan or change dispatching only for a reason

Use sudo chcpu --rescan only on systems that do not automatically detect newly attached CPUs. It asks the kernel to look for new CPUs; it does not create capacity in the hypervisor or replace the provider's hot-add operation. Verify afterwards with lscpu.

sudo chcpu --dispatch horizontal and sudo chcpu --dispatch vertical request a CPU dispatching mode, also called polarisation. The mode affects only hardware and hypervisors that support CPU polarisation. Horizontal spreads work across available CPUs; vertical concentrates work on fewer CPUs. If the platform does not support it, expect failure or no useful change. Record the original platform setting before changing it, and use the provider or hardware documentation for the rollback choice.

6. Diagnose without guessing

When a command fails, first reread the exact CPU list and check the current state:

$ lscpu | grep -E '^(CPU\(s\)|On-line CPU\(s\) list:)'
$ id -u
$ chcpu --help

Use root only when the operation needs it. sudo cannot overcome a hypervisor policy, an unsupported architecture, an invalid CPU state or a CPU list that does not exist. For a failed multi-CPU request, the exit status 64 is especially important: some CPUs may have changed while others did not. Reconcile lscpu and the per-CPU files with the maintenance record before taking another action.

Do not infer success from the absence of an error message in a copied transcript. Check the exit status immediately, then verify the resulting online list. If a service reports degraded performance or loses its expected CPU capacity, stop further changes, restore only the known-good CPU state, and involve the platform owner.