hugepages is a small CLI for inspecting and configuring the Linux
hugepage pool. It reports current totals, free, and reserved counts per
supported page size, reserves pages via the sysfs interface at
/sys/kernel/mm/hugepages/, and mounts the hugetlbfs filesystem
(default /dev/hugepages).
pipx install hugepages
Or standalone (single-file, stdlib only, no pip needed):
curl -fsSL https://raw.githubusercontent.com/xnvme/hugepages/main/src/hugepages/hugepages.py \
-o ~/.local/bin/hugepages && chmod +x ~/.local/bin/hugepages
hugepages --print-completion bash > ~/.local/share/bash-completion/completions/hugepages
Open a new shell (or source the file) and tab-completion is live: hugepages <TAB> lists info setup mount.
$ hugepages --help
usage: hugepages [-h] [--version] [--verbose] [--print-completion SHELL]
{info,setup,mount} ...
Inspect and manage Linux hugepages
positional arguments:
{info,setup,mount}
info Show hugepage status and capabilities
setup Configure hugepage pool
mount Mount hugetlbfs
options:
-h, --help show this help message and exit
--version show program's version number and exit
--verbose Enable verbose logging
--print-completion SHELL
Print shell completion script to stdout and exit
A few common invocations:
hugepages info # current pool state + supported sizes
sudo hugepages setup --count 512 # reserve 512 pages at the smallest supported size
sudo hugepages setup --size 2048 --count 1024 # reserve 1024 x 2 MiB (explicit size)
sudo hugepages mount # mount hugetlbfs at /dev/hugepages
1 GiB hugepages are only available if the kernel was booted with
default_hugepagesz=1G hugepagesz=1G hugepages=N on the cmdline; the
kernel reserves the 1 GiB pool at boot, and hugepages setup cannot
enable that size after the fact. hugepages info lists the sizes the
running kernel actually supports.
hugepages info sample output (pool not yet reserved):
Hugepage Support:
Size: 2048kB Total: 0 Free: 0 Reserved: 0
Size: 1048576kB Total: 0 Free: 0 Reserved: 0
hugepages setup reserves pages in the kernel pool. Programs that
allocate via memfd_create(..., MFD_HUGETLB) or
mmap(..., MAP_HUGETLB) draw directly from the pool; no filesystem is
needed. Modern DPDK and custom xNVMe/uPCIe code take this path.
hugepages mount additionally mounts the hugetlbfs pseudo-filesystem
(default /dev/hugepages). Programs that want file-backed hugepages
with named-page semantics open and mmap files under the mountpoint.
SPDK and classic DPDK with --huge-dir use this path.