# Build Memgraph from source

Follow this guide if you want to compile Memgraph from source. 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) (ideal for unsupported systems)

> **Note**
>
> Memgraph uses `git` for source version control. You will need to install `git`
> on your machine before you can download the source code.

> **Note**
>
> If you are using Mac M1 or above, please check our [MacOS Lima Compilation
> Guide](https://www.notion.so/MacOS-Lima-Compilation-Guide-eae1e9dcef5740579c5a41075b8f499b?pvs=21)
> first.

Please see the [Packaging Memgraph](https://memgraph.com/docs/getting-started/packaging-memgraph) guide for 
information on how to build a Memgraph package for a Linux distribution.

In every case, start by cloning the source code:

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

## About the toolchain

Memgraph is compiled with its own toolchain (currently **v8**: GCC 16.2, LLVM
22.1.8, CMake 4.4.1 and supporting tools). As of 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`

The easiest way to build Memgraph directly on a compatible host system.

```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 resulting binary will be in the `build/` directory.

> **Note**
>
> - `build.sh` requires Python 3.10 or newer. On distros whose default `python3`
>   is older (e.g. CentOS 9), install a newer one (e.g. `python3.12`) — the script
>   finds it automatically, or set `MG_PYTHON` to point at it.
> - 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`

The same operations `build.sh` performs, but 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

Builds inside Memgraph's own `mgbuild` images — nothing but Docker is needed on
the host, so this works on any system.

```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 compilation, verify that Memgraph works:

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

The unit tests can be run using:

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

Or in Docker:

```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

When build errors occur, there are some common issues that can be resolved by the following steps:

1. Remove the `build` directory and run the build again.

2. Re-run `conan install`: libraries used in the build may have been changed in
`conanfile.py`. Unexpected linking errors can be caused by this.

3. Reinstall `conan_config`. As the list of supported Linux distributions and
architectures evolves, and the libraries used in the build may change, the
configuration may need to be updated to account for specific build issues on
some platforms.

4. Reinstall host dependencies, as these may sometimes change.

5. Renaming or removing the conan cache directory (usually `~/.conan2`) in order
to rebuild the libraries and build tools from scratch can help to resolve build
issues.

6. Open an issue on our [GitHub
repository](https://github.com/memgraph/memgraph/issues) with the error message.