MatrixOne Installation Guide

October 10, 2025 · View on GitHub

This guide provides detailed instructions for installing MatrixOne on Linux and MacOS.

Installation Methods

MatrixOne supports multiple installation methods:

Using mo_ctl Tool

mo_ctl is the official command-line tool for deploying, installing, and managing MatrixOne.

Prerequisites

Install Dependencies:

  1. MySQL Client (version 8.0.30 or later recommended)

Installation Steps

Step 1: Install mo_ctl tool

wget https://raw.githubusercontent.com/matrixorigin/mo_ctl_standalone/main/install.sh && sudo -u $(whoami) bash +x ./install.sh

Step 2: Configure deployment mode

Choose between Git (source) or Docker deployment:

# Option A: Deploy from source
mo_ctl set_conf MO_PATH="yourpath"        # Set custom MatrixOne download path
mo_ctl set_conf MO_DEPLOY_MODE=git        # Set deployment method to git

# Option B: Deploy with Docker
mo_ctl set_conf MO_CONTAINER_DATA_HOST_PATH="/yourpath/mo/"  # Set data directory
mo_ctl set_conf MO_DEPLOY_MODE=docker     # Set deployment method to docker

Step 3: Deploy MatrixOne

# Deploy latest development version (main branch)
mo_ctl deploy main

# Or deploy specific stable version
mo_ctl deploy v1.2.0  # Replace with desired version

Step 4: Start MatrixOne

mo_ctl start

Note: Initial startup takes approximately 20-30 seconds.

Step 5: Connect to MatrixOne

mo_ctl connect

Common mo_ctl Commands

mo_ctl status          # Check MatrixOne status
mo_ctl stop            # Stop MatrixOne
mo_ctl restart         # Restart MatrixOne
mo_ctl upgrade         # Upgrade to latest version
mo_ctl uninstall       # Uninstall MatrixOne

For complete usage, see mo_ctl Tool Documentation.

Building from Source

Build MatrixOne from source for development or customization.

Prerequisites

1. Install Go (version 1.22 required)

Follow the official Go installation guide.

2. Install GCC/Clang

Follow the official GCC installation guide.

3. Install Git

Install via the official Git documentation.

4. Install MySQL Client

Download from MySQL Community Downloads and configure environment variables.

Build Steps

Step 1: Clone repository

git clone https://github.com/matrixorigin/matrixone.git
cd matrixone

Step 2: Prepare Dependencies

go mod vendor

Step 3: Build MatrixOne

make build

Step 4: Launch MatrixOne

./mo-service -launch ./etc/launch/launch.toml

Step 5: Connect using MySQL client

mysql -h 127.0.0.1 -P 6001 -u root -p
# Default password: 111

Using Docker

Quick deployment using Docker containers.

Prerequisites

1. Install Docker

  • Download from Docker official website
  • Recommended version: 20.10.18 or later
  • Maintain consistency between Docker client and server versions

2. Install MySQL Client

Download from MySQL Community Downloads (version 8.0.30+ recommended).

Deployment Steps

Step 1: Pull and run MatrixOne

docker run -d -p 6001:6001 --name matrixone matrixorigin/matrixone:latest

Step 2: Connect to MatrixOne

mysql -h 127.0.0.1 -P 6001 -u root -p111

Docker Compose

For production deployment with persistent storage:

version: '3'
services:
  matrixone:
    image: matrixorigin/matrixone:latest
    container_name: matrixone
    ports:
      - "6001:6001"
    volumes:
      - ./data:/var/lib/matrixone
    restart: unless-stopped

Post-Installation

After installation, consider the following:

  1. Change Default Password

  2. ⚠️ Configure Performance (Important)

    Default cache size is too small for production workloads. For better query performance, adjust the memory cache configuration:

    Edit your configuration file (launch.toml or cn.toml):

    [fileservice.cache]
memory-capacity = "8GB"  # Adjust based on available memory

    Recommended settings:

    • Development: 2-4GB
    • Production: 8-32GB (depending on workload and available RAM)

    📖 Complete Configuration Guide →

  3. Install Python SDK

    pip install matrixone-python-sdk

  4. Verify Installation

    mysql -h 127.0.0.1 -P 6001 -u root -p111 -e "SELECT VERSION()"

Troubleshooting

Performance Issues

Slow query performance? The default cache size (512MB) is likely too small.

Solution: Increase memory cache in your configuration file:

[fileservice.cache]
memory-capacity = "8GB"  # Or higher based on your needs

Restart MatrixOne after configuration changes.

📖 Performance Configuration Guide →

Connection Issues

  • Verify MatrixOne is running: mo_ctl status (if using mo_ctl)
  • Check port 6001 is not in use: lsof -i :6001
  • Review logs: mo_ctl watchdog (if using mo_ctl)

Build Issues

  • Ensure Go version 1.22 is installed: go version
  • Verify GCC is available: gcc --version
  • Check disk space and memory availability

For more help, visit: