Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

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.

    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).

    You must disable THP on Linux systems to ensure the optimal performance of Couchbase Server.

    Using Init Script

    1. 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.

    2. Make the script executable.

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

    3. Configure the OS to run the script on boot.

      console
      Copy
      sudo chkconfig --add disable-thp

    4. 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.

    5. 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.

    1. Create a new tuned directory for the new profile.

      console
      Copy
      sudo mkdir /etc/tuned/no-thp

    2. 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.

    3. 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]