Compiling MariaDB From Source: The Master Guide

Complete step-by-step guide for compiling and building MariaDB from source on various flavors of Linux and on macOS.

This guide covers compiling MariaDB on Unix-like systems, including Linux and macOS. If you are building on Windows, please refer to the dedicated Building MariaDB on Windows guide.

This guide provides the universal workflow for building MariaDB Server from source code. While specific dependencies may vary by operating system, the core build process remains consistent across all modern platforms.

Major Steps

1

Prepare Your Environment

Before you begin, your system must have the necessary compilers, build tools, and library headers.

For details, see Install Build Dependencies.

2

Obtain the Source Code

Decide whether you need the latest development branch or a specific stable release.

• Option A: Git clone (best for developers)

  git clone --branch 11.8 https://github.com/MariaDB/server.git
  cd server

• Option B: Source tarball (best for stability)

  Download the .tar.gz from the official MariaDB downloads and extract it:

  tar -xf mariadb-11.8.x.tar.gz
  cd mariadb-11.8.x

For details on both options, see Obtaining the Source Code.

3

Configure the Build (CMake)

MariaDB uses out-of-source builds to keep the source tree clean. This is where you define installation paths and features.

1. Create a build directory: mkdir build && cd build

2. Run CMake:

   cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo

   • Common flags like -DCMAKE_INSTALL_PREFIX or debug options go here.

For common CMake configuration flags, see Common CMake Configuration Flags.

For a configuration alternative to configuring CMake, see The Quick Way: Using BUILD Scripts.

4

Compile

Once configured, use the CMake build tool to compile the binaries. Using the --parallel flag speeds this up by using multiple CPU cores.

Linux

cmake --build . --parallel $(nproc)

macOS

Universal

If you encounter build errors, see Troubleshooting Common Build Errors.

5

Install and Initialize

After a successful build, you must prepare the data directory and system tables before the server can start.

1. Install: sudo cmake --install . (or run directly from the build directory for testing).

2. Create Data Directory: Ensure the mysql user exists and has permissions.

3. Initialize System Tables.

   1. If running from the build directory (use this if you did not run the cmake install command – in that case, you must run the script from within your build folder):

      ./scripts/mariadb-install-db --user=mysql --datadir=[path]

   2. If you installed to the system (sudo cmake --install ..., in which case the PATH to mariadb-install-db is set):

      mariadb-install-db --user=mysql --datadir=[path]

See this section for conventional locations of the data directory (--datadir).

6

Start and Verify

Launch the server and check that it is responsive.

./bin/mariadbd-safe --user=mysql &
./bin/mariadb -u root -p

7

Test the Build

Before putting your fresh build into production, verify it against the official test suite. MariaDB includes MTR (MariaDB Test Run) for this purpose.

1. Run Unit Tests: Quickly check the core logic.

   cmake --build . --target test

2. Run Integration Tests (MTR): This launches actual server instances and runs thousands of SQL tests.

   cd mysql-test
   ./mysql-test-run.pl --parallel=$(nproc)

   • Pro-Tip: If a specific test fails, you can run it individually: ./mysql-test-run.pl alias.

   • Note: You do not need to install MariaDB to the system to run these tests; they run entirely within the build directory.

8

After Building

After successfully building MariaDB from source, additional tasks can be found under Post-Build.

Summary of the Build Workflow

Step	Action	Primary Tool
1	Install Build Tools	apt / dnf / brew
2	Download Source	git / wget
3	Configure Features	cmake
4	Compile Binaries	cmake --build
5	Initialize Database	mariadb-install-db

Preparing Your Environment: Install Build Dependencies

This section covers the details of step 1 (Prepare Your Environment).

To compile MariaDB, you need a set of core build tools and development headers for various libraries.

Setting up the MariaDB Source Repository

Setting up the MariaDB source repository is optional but recommended. If you want to build the MariaDB version that comes with your operating system, you can skip this subsection, though.

Adding the MariaDB Repository Tool into the workflow ensures that you are getting the dependencies specifically tailored for the version of MariaDB you want to build (for instance, 11.8), rather than whatever outdated version happens to be in your operating system's default upstream repository.

Using the MariaDB Repository Tool

While your operating system's default repositories contain many build tools, they may lack the specific library versions required for the latest MariaDB releases. Using the MariaDB Repository Tool ensures your environment is perfectly synced with the version you intend to build.

1. Configure the Repository

Use the MariaDB Repository Configuration Tool to generate the setup commands for your specific operating system and desired MariaDB version.

Example for Ubuntu 24.04 and MariaDB 11.8 (don't copy this blindly – the example uses the 11.8 release and a specific mirror; adjust these strings based on the output of the Repository Configuration Tool):

sudo apt-get install software-properties-common dirmngr
sudo apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 0xF1656F24C74CD1D8
sudo add-apt-repository --update --yes --enable-source \
'deb [arch=amd64] https://mirrors.xtom.com/mariadb/repo/11.8/ubuntu noble main'

2. Install Tailored Dependencies

Once the repository is active and the source lines are enabled, you can use the package manager to pull exactly what that specific MariaDB version requires:

Ubuntu / Debian

sudo apt-get build-dep mariadb-11.8  # Replace with your target version

RHEL / CentOS / Fedora

Advantages of Using the Repository Tool

1. Version Accuracy: If MariaDB 11.x requires a newer libssl or zstd than what your operating system provides by default, the MariaDB repo often provides the correct headers.

2. Completeness: It automatically handles the "Source Repositories" issue because the add-apt-repository command includes the --enable-source flag by default.

3. Automation: It reduces the "Manual Package Table" from a primary task to a fallback for users who cannot or will not add external repositories.

The "Shortcut" Command

Most Linux distributions allow you to install all necessary dependencies for the "official" build with a single command.

This requires that "source repositories" are enabled in your package manager. Enable them like this:

Ubuntu

Run this command:

sudo add-apt-repository --update --yes --enable-source

Debian

RHEL / Alma

Fedora

The shortcut command itself varies by operating system:

Ubuntu / Debian

sudo apt build-dep mariadb-server

RHEL / CentOS / Fedora

SLES / openSUSE

macOS

Manual Package Table

If you are building a specific version or don't want to use the shortcut, use the list below to install the mandatory packages.

Ubuntu / Debian

Use apt to install these tools:

• Build tools: build-essential git cmake

• Parser tools: bison flex

• Terminal/UI: libncurses-dev

• Security/SSL: libssl-dev or gnutls-dev

• Compression: zlib1g-dev

• Miscellaneous headers: libaio-dev libboost-all-dev

RHEL / CentOS / Fedora

SLES / openSUSE

macOS

Optional Dependencies (Plugins & Features)

If you plan to enable specific storage engines or features, install these additional packages:

Feature	Dependency	Package Name (Generic)
S3 Storage Engine	libcurl	libcurl-devel / libcurl4-openssl-dev
GSSAPI (Kerberos)	krb5	krb5-devel / libkrb5-dev
RocksDB / MyRocks	snappy, lz4, zstd	snappy-devel, lz4-devel, libzstd-devel
Systemd Support	systemd	systemd-devel / libsystemd-dev
Authentication	pam	pam-devel / libpam0g-dev

Obtaining the Source Code

This section covers the details of step 2 (Obtain the Source Code).

Depending on your goal, you can either clone the repository using Git or download a stable source tarball.

Option A: Git Clone (Recommended for Developers)

Using Git allows you to easily switch between versions and contribute patches. MariaDB uses submodules for certain components; you must initialize these for the build to succeed.

1. Clone the specific branch:

   Choose a branch that matches the major version you need (for instance, 11.8).

   git clone --branch 11.8 https://github.com/MariaDB/server.git
   cd server

2. Initialize Submodules:

   This command downloads the source code for external storage engines and connectors.

   git submodule update --init --recursive

Option B: Source Tarball (Best for Stability)

If you do not need version control, downloading a pre-packaged source tarball is simpler. Submodules are already included in the tarball, so no extra steps are required.

1. Download: Visit the MariaDB Downloads page and select the "Source" tab.

2. Extract:

   tar -xf mariadb-11.8.x.tar.gz
   cd mariadb-11.8.x

Key Takeaway: Git vs. Tarball

Feature	Git Clone	Source Tarball
Updates	Easy (git pull)	Manual (download new version)
Submodules	Requires manual initialization	Pre-included
History	Full commit history available	No history included
Size	Larger (includes .git data)	Smaller

Common CMake Configuration Flags

This section covers the details of step 3 (Configure the Build).

When running cmake .., you can pass these options (using the -D prefix) to customize how MariaDB is built.

Category	Flag	Description
Install Path	-DCMAKE_INSTALL_PREFIX=/opt/mariadb	Defines where the server is installed (default: /usr/local).
Build Type	-DCMAKE_BUILD_TYPE=RelWithDebInfo	Options: Release, Debug, RelWithDebInfo (recommended).
Features	-DWITH_EMBEDDED_SERVER=ON	Builds the libmariadbd embedded library.
Storage Engines	-DPLUGIN_ROCKSDB=NO	Explicitly disables a specific storage engine (use YES to force enable).
Security	-DWITH_SSL=system	Use the system's OpenSSL (default). Options: system, openssl, gnutls.
Debugging	-DWITH_ASAN=ON	Enables AddressSanitizer to find memory leaks.
Standardization	-DBUILD_CONFIG=mysql_release	Configures the build to match the official MariaDB release binaries.

Pro-Tip: Managing Plugins

Most plugins are auto-detected based on the dependencies you installed in step 1. To see a full list of available options and their current status, run:

cmake .. -LH

The Quick Way: Using BUILD Scripts

This section covers alternative details of step 3 (Configure the Build).

If you don't want to manually toggle CMake flags, MariaDB includes a BUILD/ directory containing pre-configured scripts for common development environments. These are especially useful for developers who need a specific setup (like a Debug build with Valgrind support) quickly.

How to Use a BUILD Script

These scripts must be run from the root of the source directory (unlike the manual "out-of-source" CMake method).

# Example: Build an optimized 64-bit version with debugging symbols
./BUILD/compile-pentium64-debug

Common Script Variants

Most scripts follow a naming convention: compile-[architecture]-[type].

Script	Best For...
compile-pentium64-debug	Standard 64-bit development with debug symbols.
compile-pentium64-max	Enables almost all features and plugins (highest compatibility).
compile-pentium64-valgrind-max	Optimized for memory testing with Valgrind.
compile-amd64-debian-build	Mimics the configuration used for official Debian/Ubuntu packages.

Adding Extra Flags

You can still pass custom CMake flags to these scripts using environment variables or arguments, though most users find the defaults sufficient for testing.

./BUILD/compile-pentium64-debug --extra-configs="-DCMAKE_INSTALL_PREFIX=/tmp/mariadb"

Troubleshooting Common Build Errors

This section covers details of step 4 (Compile).

Compiling from source often hits roadblocks. Here are the most common issues and how to fix them.

Error Message	Likely Cause	Solution
CMAKE_CXX_COMPILER not found	Missing C++ compiler.	Install g++ (Linux) or clang (macOS).
Bison version is too old	macOS default bison is outdated.	brew install bison and update your PATH.
Could not find GSSAPI	Missing Kerberos headers.	Install libkrb5-dev or krb5-devel.
Could not find Curses	Missing terminal headers.	Install libncurses-dev or ncurses-devel.
No space left on device	/tmp or build dir is full.	MariaDB requires ~5GB to 10GB of disk space for a full build.

The "Clean Slate" Command

If you changed your CMake flags and things are getting weird, the best fix is to wipe the cache and start over.

# Inside your build directory
rm -rf *
cmake .. [your flags]

Do not delete the source directory, only the contents of the build folder.

Notes

Conventional Data Directory Locations

This table lists typical locations of --datadir.

Platform	Conventional Data Directory
Linux (General)	/var/lib/mysql
macOS (Homebrew)	/opt/homebrew/var/mysql
macOS (Intel/Legacy)	/usr/local/var/mysql
FreeBSD	/var/db/mysql
Custom/Dev Build	~/mariadb-data (or any folder owned by your user)

Post-Build

This section covers optional additional things to do after building MariaDB successfully (step 8 (After Building)).

Packaging

If you need to deploy MariaDB to multiple servers, you don't have to compile it on every machine. Instead, use MariaDB’s built-in packaging support to create a distributable package.

MariaDB uses CPack (part of the CMake suite) to generate these packages.

1. Configure for Packaging: To ensure the package follows standard filesystem hierarchies, use the mysql_release configuration.

   cmake .. -DBUILD_CONFIG=mysql_release

2. Generate the Package: After the build is complete, run cpack from your build directory.

   # To create the default package for your OS (DEB on Ubuntu/Debian, RPM on RHEL)
   cpack -G DEB   # For Debian-based
   cpack -G RPM   # For RedHat-based
   cpack -G TGZ   # For a generic binary tarball

3. Result: You will find a file like mariadb-11.x.x-linux-x86_64.deb in your build directory, which can be installed via dpkg -i or rpm -ivh.