# Build Memgraph from source

Compile Memgraph from source with Memgraph's own toolchain. There are three
self-contained ways to build; pick one:

1. [Using the `build.sh` script](#build-with-buildsh) (recommended)
2. [Manually with `conan` and `cmake`](#build-with-conan-and-cmake) (advanced)
3. [Using Docker](#build-with-docker) (for systems the other two methods don't support)

On a Mac with Apple silicon, follow the [macOS Lima compilation
guide](https://www.notion.so/MacOS-Lima-Compilation-Guide-eae1e9dcef5740579c5a41075b8f499b)
first.

To build a `.deb` or `.rpm` package after the build, see [Package
Memgraph](https://memgraph.com/docs/getting-started/install-memgraph/packaging).

In every case, install `git` and clone the source code:

```bash
git clone git@github.com:memgraph/memgraph.git
cd memgraph
```

## About the toolchain

Memgraph is compiled with its own toolchain (**v8**: GCC 16.2, LLVM
22.1.8, CMake 4.4.1 and supporting tools). Since v8, the toolchain bundles its
own sysroot and is **distro-agnostic** — a single archive per architecture that
works on any Linux with glibc 2.31 or newer:

- [Toolchain v8 (x86_64)](https://s3-eu-west-1.amazonaws.com/deps.memgraph.io/toolchain-v8/toolchain-v8-binaries-x86_64.tar.gz)
- [Toolchain v8 (aarch64)](https://s3-eu-west-1.amazonaws.com/deps.memgraph.io/toolchain-v8/toolchain-v8-binaries-aarch64.tar.gz)

The build sections below include the download/extract step; see
[`memgraph/environment`](https://github.com/memgraph/memgraph/tree/master/environment)
for how the toolchain itself is built.

## Build with `build.sh`

Build Memgraph directly on a compatible Linux host.

```bash
# Install system packages: toolchain runtime deps + Memgraph build deps
# (auto-detects your distro; scripts live under environment/os/)
sudo ./environment/os/install_deps.sh install TOOLCHAIN_RUN_DEPS
sudo ./environment/os/install_deps.sh install MEMGRAPH_BUILD_DEPS

# Install the toolchain to /opt/toolchain-v8 (use the aarch64 archive on ARM)
wget https://s3-eu-west-1.amazonaws.com/deps.memgraph.io/toolchain-v8/toolchain-v8-binaries-x86_64.tar.gz
sudo tar xzvfm toolchain-v8-binaries-x86_64.tar.gz -C /opt

# Rust is required for parts of the build — install via rustup if missing
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

# Build everything (tests included) in Release mode
./build.sh
```

Useful variations:

```bash
# Specific target and build type (Release, RelWithDebInfo or Debug)
./build.sh --target memgraph --build-type Debug

# Fast incremental developer rebuild
./build.sh --dev

# Build MAGE query modules together with Memgraph
./build.sh --mage on

# Pass extra cmake options directly
./build.sh --target memgraph -DMG_ENABLE_TESTING=OFF
```

The build writes the binary to the `build/` directory.

> **Info**
>
> - `build.sh` requires Python 3.10 or newer. On distributions whose default
>   `python3` is older (such as CentOS 9), install a newer one (such as
>   `python3.12`). The script finds it, or you can set `MG_PYTHON` to its path.
> - If the toolchain lives somewhere other than `/opt/toolchain-v8`, set the
>   `MG_TOOLCHAIN_ROOT` environment variable to its location.

## Build with `conan` and `cmake`

This runs the same steps as `build.sh`, with direct control over each
step. Complete the system-package and toolchain steps first:

```bash
# System packages + toolchain, same as the build.sh section
sudo ./environment/os/install_deps.sh install TOOLCHAIN_RUN_DEPS
sudo ./environment/os/install_deps.sh install MEMGRAPH_BUILD_DEPS
wget https://s3-eu-west-1.amazonaws.com/deps.memgraph.io/toolchain-v8/toolchain-v8-binaries-x86_64.tar.gz
sudo tar xzvfm toolchain-v8-binaries-x86_64.tar.gz -C /opt
```

Then build:

```bash
# conan (a C/C++ package manager) drives all third-party dependencies;
# conan_config + conan_recipes hold Memgraph's build configuration and
# vendored recipe patches
python3 -m venv env && source env/bin/activate
pip install "conan>=2.26.0"
conan profile detect
conan config install conan_config
conan remote add memgraph-recipes "$(pwd)/conan_recipes" -t local-recipes-index --force

# Resolve/build the dependencies against the toolchain, then load the build env
export MG_TOOLCHAIN_ROOT=/opt/toolchain-v8
conan install . --build=missing \
  -pr:h memgraph_toolchain_v8 \
  -pr:b memgraph_build_profile \
  -s build_type=Release
source build/generators/conanbuild.sh

# Configure and build; the preset name follows the build type
# (conan-release, conan-relwithdebinfo or conan-debug)
cmake --preset conan-release
cmake --build --preset conan-release -j$(nproc)

# ...or build a specific target only
cmake --build --preset conan-release --target memgraph -j$(nproc)
```

## Build with Docker

Build inside Memgraph's own `mgbuild` images. The host needs only Docker.

```bash
export OS="ubuntu-24.04"
export ARCH="amd"  # or arm
export BUILD_TYPE="Release"
export TOOLCHAIN="v8"

docker pull memgraph/mgbuild:v8_$OS

# Start the build container, then build Memgraph inside it
./release/package/mgbuild.sh --toolchain $TOOLCHAIN --os $OS --arch $ARCH \
  --build-type $BUILD_TYPE run
./release/package/mgbuild.sh --toolchain $TOOLCHAIN --os $OS --arch $ARCH \
  --build-type $BUILD_TYPE build-memgraph

# Run the freshly built Memgraph inside the container
docker exec -i mgbuild_v8_$OS bash -c "cd /home/mg/memgraph && ./build/memgraph"

# Stop and remove the container when done
./release/package/mgbuild.sh --toolchain $TOOLCHAIN --os $OS --arch $ARCH \
  stop --remove
```

## Run Memgraph

After the build, check that Memgraph runs:

```bash
./build/memgraph --version
```

Run the unit tests:

```bash
ctest -R unit -j$(nproc)
```

To run them in Docker, pass your Enterprise license and organization name
from the `MEMGRAPH_ENTERPRISE_LICENSE` and `MEMGRAPH_ORGANIZATION_NAME`
environment variables:

```bash
./release/package/mgbuild.sh \
  --toolchain $TOOLCHAIN \
  --os $OS \
  --arch $ARCH \
  --enterprise-license $MEMGRAPH_ENTERPRISE_LICENSE \
  --organization-name $MEMGRAPH_ORGANIZATION_NAME \
  test-memgraph unit
```

## Troubleshoot

If the build fails, try these steps in order:

1. Remove the `build` directory and run the build again.
2. Run `conan install` again. The libraries in `conanfile.py` may have changed,
   which causes unexpected linking errors.
3. Reinstall `conan_config`. The build configuration changes as supported
   distributions, architectures and libraries change.
4. Reinstall the host dependencies, which also change over time.
5. Rename or remove the conan cache directory (usually `~/.conan2`) to rebuild
   the libraries and build tools from scratch.
6. Open an issue on [GitHub](https://github.com/memgraph/memgraph/issues) with
   the error message.