How do I enable huge pages inside a Docker container for XMRig?

To enable huge pages for XMRig in Docker, reserve the memory on your Linux host, then give the container permission to use it. Turn on huge pages in XMRig and check its startup log—Docker does not create a separate huge-page pool for each container.

1. Reserve huge pages on the host

Huge pages are larger-than-normal blocks of memory. They reduce memory-management work, which can improve performance when XMRig runs RandomX, Monero’s mining algorithm.

First, check your host:

grep -i huge /proc/meminfo

Look for Hugepagesize: 2048 kB. The instructions below assume these standard 2 MB huge pages.

For one RandomX mining instance on a machine with one memory node, reserve 1,280 pages:

sudo sysctl -w vm.nr_hugepages=1280

That reserves about 2.5 GB of RAM. It is a useful starting point, not a universal requirement. RandomX’s fast mode uses a 2,080 MB dataset, plus cache and working memory. Multiple memory nodes or more mining threads can require additional pages.

Check again:

grep -E 'HugePages|Hugepagesize' /proc/meminfo

HugePages_Total should reflect the reservation. If it falls short, memory fragmentation may be preventing allocation. Reserving pages shortly after a reboot can help.

To keep the setting after reboot:

echo 'vm.nr_hugepages=1280' | sudo tee /etc/sysctl.d/80-xmrig-hugepages.conf

Reserved huge pages are unavailable for ordinary application memory, so leave enough RAM for your host and other containers.

2. Enable huge pages in XMRig

In your existing config.json, make sure the cpu section includes:

"cpu": {
  "enabled": true,
  "huge-pages": true
}

Merge these settings into your existing section rather than creating a second cpu section. Keep your pool, wallet, and other settings.

These instructions enable ordinary 2 MB huge pages. XMRig’s optional 1 GB pages are a separate feature with different host setup requirements.

3. Start Docker with the needed permissions

For a trusted image that provides xmrig in its executable search path, use:

docker run --rm --name xmrig \
  --user 0:0 \
  --cap-add=IPC_LOCK \
  --ulimit memlock=-1:-1 \
  --mount type=bind,src="$(pwd)/config.json",dst=/xmrig/config.json,readonly \
  --entrypoint xmrig \
  YOUR_XMRIG_IMAGE \
  -c /xmrig/config.json

Replace YOUR_XMRIG_IMAGE with your trusted image name. Adjust the entrypoint if its executable lives elsewhere.

• IPC_LOCK grants permission needed for certain locked-memory and huge-page operations.
• memlock=-1:-1 removes the container’s locked-memory limit.
• --user 0:0 runs XMRig as root inside the container, simplifying permission setup.

You do not normally need --privileged, host IPC sharing, or a mounted huge-page filesystem. Prefer narrower permissions over a fully privileged container.

4. Verify allocation, not just support

Read XMRig’s startup output. Look for successful huge-page allocation, ideally 100% for its RandomX memory and mining threads. An “available” message alone does not prove allocation succeeded.

If allocation fails, check:

• Whether other miners already consumed the host’s free huge pages.
• Whether container memory or huge-page resource limits block allocation.
• Whether a multi-node memory system needs pages reserved on each node.
• Whether rootless Docker or a virtual machine restricts access.

With Docker Desktop, configure the Linux virtual machine hosting Docker—not just Windows or macOS.

The bottom line

Reserve huge pages on the host, enable them in XMRig, and grant targeted container permissions. Confirm successful allocation in the logs before assuming your miner benefits.