Back to Commands

numactl

systemLinux
The numactl command is one of the most frequently used commands in Linux/Unix-like operating systems. numactl Control NUMA policy for processes or shared memory
See ExamplesView Syntax

Quick Reference

Command Name:

numactl

Category:

system

Platform:

Linux

Basic Usage:

numactl [options] [arguments]

Common Use Cases

    Syntax

    numactl [options] -- program [arguments]

    Options

    Option Description
    --hardware, -H Show hardware configuration
    --show, -s Show NUMA policy settings of current process
    --membind=nodes, -m nodes Only allocate memory from specified nodes
    --cpunodebind=nodes, -N nodes Only execute process on CPUs of specified nodes
    --physcpubind=cpus, -C cpus Only execute process on specified physical CPUs
    --localalloc, -l Allocate memory on the current node
    --preferred=node, -p node Prefer memory allocations from specified node
    --interleave=nodes, -i nodes Interleave memory allocations between nodes
    --offset=offset, -o offset Set offset in shared memory segment (for --shmid option)
    --shmmode=mode Set shared memory segment mode (for --shmid option)
    --length=length, -L length Set length of shared memory segment (for --shmid option)
    --shmid=id Operate on shared memory segment with specified id
    --huge Use huge pages for shared memory segment
    --touch Touch pages before process startup (for --shmid option)

    Node Specification Format:

    Format Description
    number Single node (e.g., 0, 1, 2)
    number1-number2 Range of nodes (e.g., 0-2 means nodes 0, 1, 2)
    number1,number2,... List of nodes (e.g., 0,2 means nodes 0 and 2)
    all All online nodes

    Examples

    How to Use These Examples

    The examples below show common ways to use the numactl command. Try them in your terminal to see the results. You can copy any example by clicking on the code block.

    # Basic Examples Basic
    numactl --show
    Display the NUMA policy settings of the current process.
    numactl --hardware
    Show hardware NUMA configuration of the system.
    # Advanced Examples Advanced
    numactl --cpunodebind=0 --membind=0 -- myprogram Run myprogram on CPUs of node 0 with memory allocated only on node 0. numactl --physcpubind=0-4 -- myprogram Run myprogram on physical CPUs 0 to 4. numactl --interleave=all -- myprogram Run myprogram with memory interleaved on all nodes. numactl --preferred=1 -- myprogram Run myprogram with a preferred memory allocation on node 1. numactl --localalloc -- myprogram Run myprogram with local memory allocation policy. numactl --cpunodebind=0,1 --membind=0,1 -- myprogram Run myprogram on CPUs of nodes 0 and 1 with memory allocated only on nodes 0 and 1. numactl --physcpubind=0,2,4,6 -- myprogram Run myprogram on physical CPUs 0, 2, 4, and 6 (useful for hyperthreaded systems). numactl --cpunodebind=1 -- numactl --show Run numactl --show on CPUs of node 1 to see the NUMA policy.

    Try It Yourself

    Practice makes perfect! The best way to learn is by trying these examples on your own system with real files.

    Understanding Syntax

    Pay attention to the syntax coloring: commands, options, and file paths are highlighted differently.

    Notes

    The numactl command is a powerful utility for controlling NUMA (Non-Uniform Memory Access) policy for processes or shared memory in Linux systems. NUMA is a memory design used in multiprocessor systems where the memory access time depends on the memory location relative to the processor. In NUMA architectures, a processor can access its local memory faster than non-local memory (memory local to another processor or memory shared between processors). As modern server systems increasingly use NUMA architectures to scale performance, numactl has become an essential tool for system administrators and performance engineers who need to optimize application performance on these systems. Key features of the numactl command: 1. Process Execution Control: numactl allows you to start processes with specific NUMA policies, controlling which CPUs they run on and which memory nodes they allocate from. 2. Memory Policy Management: The tool provides several memory allocation policies, including binding memory to specific nodes, interleaving memory across nodes, and setting preferred nodes for allocation. 3. Hardware Information: The --hardware option displays detailed information about the NUMA topology of the system, including the number of nodes, the memory available on each node, and the CPUs associated with each node. 4. Policy Inspection: Using the --show option lets you view the current NUMA policy settings for the running process. 5. Shared Memory Control: numactl can also set NUMA policy for shared memory segments, which is useful for applications that use shared memory for inter-process communication. Common use cases for numactl include: - Improving performance of memory-intensive applications by ensuring they use local memory - Isolating critical applications to specific NUMA nodes to reduce contention - Load balancing across NUMA nodes by interleaving memory allocations - Performance testing to understand the impact of different NUMA policies - Database optimization, particularly for large in-memory databases - HPC (High-Performance Computing) applications that benefit from careful CPU and memory placement When using numactl, it's important to understand your system's NUMA topology. The performance benefits of different NUMA policies can vary significantly depending on the workload characteristics and the hardware configuration. In some cases, binding a process to a specific node might improve performance by increasing memory locality, while in other cases, interleaving memory across nodes might provide better overall throughput. For development and benchmarking purposes, numactl is invaluable for testing how applications perform under different NUMA configurations without modifying the application code. This can help identify whether an application would benefit from NUMA-aware programming techniques. numactl is typically available in most Linux distributions through their package management systems. It's often part of the 'numactl' package, which might also include related utilities like 'numademo' for NUMA benchmarking and 'memhog' for memory allocation testing.

    Related Commands

    These commands are frequently used alongside numactl or serve similar purposes:

    taskset
    libnuma
    numastat
    numademo
    lscpu
    hwloc
    lstopo
    Explore All Commands

    Use Cases

    Learn By Doing

    The best way to learn Linux commands is by practicing. Try out these examples in your terminal to build muscle memory and understand how the numactl command works in different scenarios.

    See ExamplesTry Lab Exercises
    $ numactl
    View All Commands