Disabling Transparent Huge Pages (THP)

March 23, 2025

+ 12

Transparent huge pages (THP) is a memory management system that is enabled by default in most Linux operating systems.

THP must be disabled in order for Couchbase Server to function correctly on Linux, as having THP enabled can worsen performance and possibly lead to an OOM kill.

In Linux operating systems, huge pages is a feature that provides a way for the CPU and OS to create pre-allocated contiguous memory space, and which is designed to improve application performance. Transparent huge pages (THP) is a Linux OS feature that automates the creation of contiguous memory space and conceals much of the complexity of using actual huge pages on systems with large amounts of memory.

THP is enabled by default in most Linux operating systems, and functions very well for most applications and processes. However, THP is detrimental to Couchbase’s performance (as it is for nearly all databases that tend to have sparse rather than contiguous memory access patterns).

Since we tend to have more random, sparse data access, we allocate pages that can remain mostly empty. This leads to memory fragmentation as portions of memory are not used but still accounted for in the RSS. As a result, the data stored which we keep track of may be smaller while RSS can be significantly higher, leading to possible OOM kill.

Therefore, you must disable THP on Linux systems to ensure the optimal performance of Couchbase Server.

If you are using Rocky Linux, then use the instructions to install the THP disabler as a system service.

Using Init Script

Create the init script.

console
Copy
vi /etc/init.d/disable-thp

Add the following contents:

bash
Copy
#!/bin/bash
### BEGIN INIT INFO
# Provides:          disable-thp
# Required-Start:    $local_fs
# Required-Stop:
# X-Start-Before:    couchbase-server
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Disable THP
# Description:       Disables transparent huge pages (THP) on boot, to improve
#                    Couchbase performance.
### END INIT INFO

case $1 in
  start)
    if [ -d /sys/kernel/mm/transparent_hugepage ]; then
      thp_path=/sys/kernel/mm/transparent_hugepage
    elif [ -d /sys/kernel/mm/redhat_transparent_hugepage ]; then
      thp_path=/sys/kernel/mm/redhat_transparent_hugepage
    else
      return 0
    fi

    echo 'never' > ${thp_path}/enabled
    echo 'never' > ${thp_path}/defrag

    re='^[0-1]+$'
    if [[ $(cat ${thp_path}/khugepaged/defrag) =~ $re ]]
    then
      # RHEL 7
      echo 0  > ${thp_path}/khugepaged/defrag
    else
      # RHEL 6
      echo 'no' > ${thp_path}/khugepaged/defrag
    fi

    unset re
    unset thp_path
    ;;
esac

Save and close your editor.

Make the script executable.

console
Copy
sudo chmod 755 /etc/init.d/disable-thp

Configure the OS to run the script on boot.

Red Hat, CentOS, & Amazon Linux
Ubuntu & Debian
SUSE

console
Copy
sudo chkconfig --add disable-thp

console
Copy
sudo update-rc.d disable-thp defaults

console
Copy
sudo insserv /etc/init.d/disable-thp

Override tuned and ktune, if necessary.

If you are using tuned or ktune (for example, if you are running Red Hat/CentOS 7+) you must also configure them to preserve the above settings after reboot.
Reboot the system and verify that THP is disabled.

If Using `tuned` and `ktune`

tuned and ktune are system monitoring and tuning tools available on Red Hat and CentOS. When they are in use on a system, they can be used to enable and disable THP.

To disable THP in tuned and ktune, you need to edit or create a new profile that sets THP to never.

Red Hat/CentOS 7

Create a new tuned directory for the new profile.
```
console
Copy
sudo mkdir /etc/tuned/no-thp
```

Create and edit tuned.conf.

console
Copy
vi /etc/tuned/no-thp/tuned.conf

Add the following contents:

console
Copy
[main]
include=virtual-guest

[vm]
transparent_hugepages=never

Save and close your editor.

Enable the new profile.

console
Copy
sudo tuned-adm profile no-thp

Verify THP Status

You can check the THP status by issuing the following commands.

Red Hat, CentOS, & Amazon Linux

console
Copy
cat /sys/kernel/mm/transparent_hugepage/enabled

console
Copy
cat /sys/kernel/mm/transparent_hugepage/defrag

Other Linux Variants

console
Copy
cat /sys/kernel/mm/transparent_hugepage/enabled

console
Copy
cat /sys/kernel/mm/transparent_hugepage/defrag

If THP is properly disabled, the output of both commands should be the following:

console
Copy
always madvise [never]

Using a THP Service

Create a service file.

console
Copy
vi /etc/systemd/system/disable-thp.service

Add the service configuration details to the file and then save it.

console
Copy
[Unit]
Description=Disable Transparent Huge Pages (THP)
DefaultDependencies=no
After=sysinit.target local-fs.target
Before=couchbase-server.service

[Service]
Type=oneshot
ExecStart=/bin/sh -c 'echo never | tee /sys/kernel/mm/transparent_hugepage/enabled > /dev/null'
ExecStart=/bin/sh -c 'echo never | tee /sys/kernel/mm/transparent_hugepage/defrag > /dev/null'

[Install]
WantedBy=basic.target

Reload the systemctl files.
```
console
Copy
sudo systemctl daemon-reload
```

Start the service.

console
Copy
sudo systemctl start disable-thp

Ensure that the service will start whenever the system is rebooted.
```
console
Copy
sudo systemctl enable disable-thp
```

Verify THP is Disabled

Execute the following commands to ensure the service has disabled the THP.

console
Copy
cat /sys/kernel/mm/transparent_hugepage/enabled
cat /sys/kernel/mm/transparent_hugepage/defrag