# Install MAGE graph algorithm library

Use MAGE with an instance installed within a [Docker container](#docker), from a
prebuilt [package](#install-from-a-package) on Ubuntu or CentOS, or [built from
source](#build-from-source-linux). 

## Docker

[Install Memgraph with Docker](https://memgraph.com/docs/getting-started/install-memgraph/docker) using
`memgraph-platform` or `memgraph-mage` images which include the MAGE library so
no additional installation is required to run the graph algorithms on your
data. 

> **Info**
>
> You can download a specific version of MAGE
>
> For example, if you want to download version `3.2`, you should run the following
> command:
>
> ```shell
docker run -p 7687:7687 --name memgraph memgraph/memgraph-mage:3.2
```
>
> The following tags are available on Docker Hub:
> - `x.y` - production MAGE image
> - `x.y-relwithdebinfo` - contains debugging symbols and `gdb`
> - `x.y-malloc` - Memgraph compiled with `malloc`instead of `jemalloc` (x86_64 only)
> - `x.y-relwithdebinfo-cuda` - Memgraph built with CUDA support* - available since version `3.6.1`.
>
> *To run GPU-accelerated algorithms, you need to launch the container with the `--gpus all` flag.
> This requires the installation of NVIDIA Container Toolkit. See the
> [NVIDIA Container Toolkit documentation](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
> for more details.
>
> For versions prior to `3.2`, MAGE image tags included both MAGE and Memgraph versions, e.g.
>
> ```shell
docker run -p 7687:7687 --name memgraph memgraph/memgraph-mage:3.1.1-memgraph-3.1.1
```
>
> A `no-ml` image (e.g. `3.1.1-memgraph-3.1.1-no-ml`) was also provided, but this has now been
> discontinued as of `3.2` onwards.

## Install from a package

MAGE is available as a prebuilt `memgraph-mage` package, so you don't have to
build it from source. As of Memgraph 3.13, a single distro-agnostic DEB and RPM
package is shipped per architecture. MAGE currently requires **Python 3.12**;
it is tested on Ubuntu 24.04 and CentOS 9/10 — other distributions may work but
are untested.

### Install Memgraph

Install the Memgraph package first — the `memgraph-mage` package depends on a
matching `memgraph` package of the same version. Follow the
[Ubuntu](https://memgraph.com/docs/getting-started/install-memgraph/ubuntu) or
[CentOS](https://memgraph.com/docs/getting-started/install-memgraph/centos) installation guide.

### Download the MAGE package

Download the `memgraph-mage` package that matches your Memgraph version and distro
from the [direct download
links](https://memgraph.com/docs/getting-started/install-memgraph/direct-download-links). For example:

```shell
# DEB (Debian/Ubuntu)
wget https://download.memgraph.com/memgraph-mage/v3.13.0/deb/memgraph-mage_3.13.0-1_amd64.deb
# RPM (RHEL/CentOS/Rocky/Fedora)
wget https://download.memgraph.com/memgraph-mage/v3.13.0/rpm/memgraph-mage-3.13.0_1-1.x86_64.rpm
```

CUDA and cuGraph variants are also available — see the download links page.

### Install MAGE

Install the package with your distribution's package manager so its dependencies
are resolved:

```shell
# DEB (Debian/Ubuntu)
sudo apt install ./memgraph-mage_3.13.0-1_amd64.deb
# RPM (RHEL/CentOS/Rocky/Fedora)
sudo dnf install ./memgraph-mage-3.13.0_1-1.x86_64.rpm
```

> **Info**
>
> During installation the package downloads and installs the Python dependencies
> the MAGE query modules need, so the machine needs network access.

### Restart Memgraph

Restart Memgraph so the newly installed modules are loaded:

```shell
sudo systemctl restart memgraph
```

## Build from source (Linux)

Follow the steps if you want to use the MAGE library with [installed Linux based
Memgraph package](https://memgraph.com/docs/getting-started/install-memgraph). 

### Make sure the instance is not running

Algorithms and query modules will be loaded into a Memgraph instance on startup
once you install MAGE, so make sure your instances are not running. 

### Download the Memgraph source code

MAGE is developed and built as part of the Memgraph repository. Clone the
[Memgraph source code](https://github.com/memgraph/memgraph) from GitHub
(install `git` first if you don't have it — `sudo apt-get install -y git`):

```
git clone https://github.com/memgraph/memgraph.git && cd memgraph/
```

### Install dependencies

The repository ships scripts that install everything the toolchain and the
build need — `build.sh` checks for both sets and stops if anything is
missing:

```bash
sudo ./environment/os/install_deps.sh install TOOLCHAIN_RUN_DEPS
sudo ./environment/os/install_deps.sh install MEMGRAPH_BUILD_DEPS
```

### Set up the toolchain

Download and install the [Memgraph Toolchain](https://memgraph.com/docs/getting-started/build-memgraph-from-source#about-the-toolchain):
```bash
curl -L https://s3-eu-west-1.amazonaws.com/deps.memgraph.io/toolchain-v8/toolchain-v8-binaries-x86_64.tar.gz -o toolchain.tar.gz
sudo tar xzvfm toolchain.tar.gz -C /opt
```

### Install Rust and Python dependencies

Run the following commands from the root of the repository to install Rust
and the Python packages the MAGE query modules use at runtime:

```shell
source environment/util.sh
install_rust 1.89
python3 -m pip install -r src/mage/python/requirements.txt 
python3 -m pip install -r src/auth/reference_modules/requirements.txt
python3 -m pip install torch-sparse torch-cluster torch-spline-conv torch-geometric torch-scatter -f https://data.pyg.org/whl/torch-2.8.0+cpu.html
python3 -m pip install dgl -f https://data.dgl.ai/wheels/torch-2.8/repo.html
```

> **Info**
>
> To install the dependencies for GPU-accelerated algorithms, you need to use the GPU-specific requirements file:
>
> ```shell
python3 -m pip install -r src/mage/python/requirements-gpu.txt
```

### Build and install MAGE

MAGE is built with the same build system as Memgraph. Run the following
commands from the root of the repository:

```shell
source /opt/toolchain-v8/activate
./build.sh --mage only
sudo cmake --install build --component mage --prefix /usr
```

`./build.sh --mage only` builds just the MAGE query modules (C++, Python and
Rust) without Memgraph itself — the script sets up everything else it needs
(a Python virtual environment, the Conan package manager and the project's
dependencies) on first run. The built modules land in `build/mage/dist`.

The `cmake --install` command then installs the modules to
`/usr/lib/memgraph/query_modules`, the directory Memgraph loads query modules
from, together with the runtime libraries they need.

> **Info**
>
> If you don't need all of the algorithms, you can build a subset by passing
> specific targets:
>
> ```shell
# Only the Python modules (a copy step - fast)
./build.sh --mage only --target mage_python_modules

# Only the Rust modules
./build.sh --mage only --target mage_rust_modules

# Individual C++ modules by name
./build.sh --mage only --target map text
```

If something isn't set up properly, the build will stop with an error. If you
have any questions, contact us on
**[Discord](https://discord.gg/memgraph).**

### Start a Memgraph instance

Algorithms and query modules will be loaded into a Memgraph instance on startup

If your instance was already running you will need to execute the following
query to load them:

```
CALL mg.load_all();
```

If your changes are not loaded, make sure to restart the instance by running
`systemctl stop memgraph` and `systemctl start memgraph`.