Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Monarch 🦋

Monarch is a distributed programming framework for PyTorch based on scalable actor messaging. It provides:

  1. Remote actors with scalable messaging: Actors are grouped into collections called meshes and messages can be broadcast to all members.
  2. Fault tolerance through supervision trees: Actors and processes form a tree and failures propagate up the tree, providing good default error behavior and enabling fine-grained fault recovery.
  3. Point-to-point RDMA transfers: cheap registration of any GPU or CPU memory in a process, with the one-sided transfers based on libibverbs
  4. Distributed tensors: actors can work with tensor objects sharded across processes

Monarch code imperatively describes how to create processes and actors using a simple python API:

from monarch.actor import Actor, endpoint, this_host

# spawn 8 trainer processes one for each gpu
training_procs = this_host().spawn_procs({"gpus": 8})


# define the actor to run on each process
class Trainer(Actor):
    @endpoint
    def train(self, step: int): ...


# create the trainers
trainers = training_procs.spawn("trainers", Trainer)

# tell all the trainers to take a step
fut = trainers.train.call(step=0)

# wait for all trainers to complete
fut.get()

The introduction to monarch concepts provides an introduction to using these features.

📖 Documentation

View Monarch's hosted documentation at this link.

Installation

Installing from Pre-built Wheels

Monarch provides pre-built wheels that work regardless of what version of PyTorch you have installed. You can get these with pip or uv:

  • Using PIP:
    • stable: pip install torchmonarch
    • nightly: pip install --pre torchmonarch
    • specific: pip install torchmonarch==v0.7.0.dev20260713
  • Using UV - note, you can also just use uv pip install ... and match the above pip commands; but the ones below add monarch to your UV project properly.
    • stable: uv add torchmonarch
    • nightly: uv add --prerelease=allow torchmonarch
    • specific: uv add torchmonarch==v0.7.0.dev20260713

Build and Install from Source

Note: Building from source requires additional system dependencies. These are needed at build time only, not at runtime.

Monarch uses uv for fast, reliable Python package management. If you don't have uv installed:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or on macOS
brew install uv

Configuring PyTorch Index: By default, Monarch builds with PyTorch from the pytorch-cu132 index (CUDA 13.2). To use a different CUDA version:

  • Edit [tool.uv.sources] in pyproject.toml to point to a different index (e.g., pytorch-cu130, or pytorch-cpu)
  • Or use --extra-index-url when running uv:
    uv sync --extra-index-url https://download.pytorch.org/whl/cu130
    

Understanding Tensor Engine

Monarch includes distributed tensor and RDMA APIs. The tensor engine builds on any platform, including CPU-only hosts and macOS; GPU-specific pieces (NCCL, RDMA, rdmaxcel) layer on top and only build on Linux with a CUDA or ROCm toolchain installed. If you want a lighter-weight version of Monarch (actors only, no torch dependency), set USE_TENSOR_ENGINE=0.

By default, Monarch builds with tensor_engine enabled. To build without it:

USE_TENSOR_ENGINE=0 uv sync

Note: Building without tensor_engine means you won't have access to the distributed tensor or RDMA APIs. Torch is required to use tensor_engine, and the latest stable torch is ABI compatible with the latest versioned torchmonarch

Selecting a GPU platform: The MONARCH_GPU_PLATFORM environment variable controls which GPU libraries the build links against. It accepts:

  • cuda — build against CUDA (NCCL + RDMA).
  • rocm — build against ROCm.
  • none — force a CPU-only tensor engine even on a host where CUDA or ROCm is installed.

Leaving it unset auto-detects whichever toolchain is present. Setting it explicitly is required when both CUDA and ROCm are installed, and none is the explicit opt-out when you want the CPU tensor engine on a GPU-capable host.

# Force a CPU-only tensor engine (no CUDA/ROCm/RDMA libraries required)
MONARCH_GPU_PLATFORM=none uv sync

# Force CUDA on a host that also has ROCm
MONARCH_GPU_PLATFORM=cuda uv sync

Build Dependencies by Platform

On Fedora distributions
# Install nightly rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly
rustup default nightly

# Install non-python dependencies
sudo dnf install -y cmake ninja-build protobuf-compiler libunwind

# Install the correct cuda and cuda-toolkit versions for your machine
sudo dnf install cuda-toolkit-13-2 cuda-13-2

# Install clang-devel, nccl-devel, and libstdc++-static
sudo dnf install clang-devel libnccl-devel libstdc++-static

# Install RDMA libraries (needed for tensor_engine builds)
sudo dnf install -y libibverbs rdma-core libmlx5 libibverbs-devel rdma-core-devel

# Clone and sync dependencies
git clone https://github.com/meta-pytorch/monarch.git
cd monarch

# Install in development mode with all dependencies
uv sync

# Or install without tensor_engine
USE_TENSOR_ENGINE=0 uv sync

# Verify installation
uv run python -c "from monarch import actor; print('Monarch installed successfully')"

# Rebuild (e.g., after changing Rust code)
USE_TENSOR_ENGINE=0 uv pip install -e .
On Ubuntu distributions
# Install nightly rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup toolchain install nightly
rustup default nightly

# Install Ubuntu-specific system dependencies
sudo apt install -y cmake ninja-build protobuf-compiler libunwind-dev clang

# Set clang as the default C/C++ compiler
export CC=clang
export CXX=clang++

# Install the correct cuda and cuda-toolkit versions for your machine
sudo apt install -y cuda-toolkit-13-2 cuda-13-2

# Install RDMA libraries (needed for tensor_engine builds)
sudo apt install -y rdma-core libibverbs1 libmlx5-1 libibverbs-dev

# Clone and sync dependencies
git clone https://github.com/meta-pytorch/monarch.git
cd monarch

# Install in development mode with all dependencies
uv sync

# Or install without tensor_engine (CPU-only)
USE_TENSOR_ENGINE=0 uv sync

# Verify installation
uv run python -c "from monarch import actor; print('Monarch installed successfully')"

# Rebuild (e.g., after changing Rust code)
USE_TENSOR_ENGINE=0 uv pip install -e .
On non-CUDA machines

You can also build Monarch on non-CUDA machines (e.g., macOS laptops) for CPU-only usage. The tensor engine itself works on CPU; only the GPU-specific bits (NCCL, RDMA, rdmaxcel) are skipped. Auto-detection handles hosts with no CUDA or ROCm installed. If your host does have a GPU toolchain installed but you want the CPU tensor engine anyway, set MONARCH_GPU_PLATFORM=none.

# Install nightly rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install nightly
rustup default nightly

# Clone and sync dependencies
git clone https://github.com/meta-pytorch/monarch.git
cd monarch

# Build the CPU tensor engine (auto-detects no GPU)
uv sync

# Or, to skip the tensor engine entirely (actors only, no torch required)
USE_TENSOR_ENGINE=0 uv sync

# Verify installation
uv run python -c "from monarch import actor; print('Monarch installed successfully')"

Alternative: Using pip

If you prefer to use pip instead of uv:

# After installing system dependencies (see above)

# Install build dependencies

# Build and install Monarch
pip install .

# Or for development
pip install -e .

# Without tensor_engine
USE_TENSOR_ENGINE=0 pip install -e .

Building a Docker Image from Source

To build a Docker image that bundles your from-source build of Monarch — for example, to run Monarch on a Kubernetes cluster — first build a wheel, then build the image from that wheel. This picks up changes to both the Rust and Python code.

# Make sure to build for python 3.12 since the pytorch base image uses that python version
uv python pin 3.12
# Build the binary distribution, outputs to "dist/" directory.
# --no-build-isolation allows using cached rust builds which speeds up subsequent
# iterations.
uv build --no-build-isolation --wheel

# With docker:
# Build and tag a docker image with your build of monarch. You can update the
# PYTORCH_TAG to use a different base image depending on your needs.
# The nightly dockerfile is used because it uses the package you already built,
# rather than downloading from PyPI. The wheels are supplied through the
# "monarch-wheels" named build context, which the Dockerfile copies from.
docker build -f Dockerfile.nightly \
  -t $USER/monarch:local-tag \
  --build-arg PYTORCH_TAG=2.14.0.dev20260713-cuda13.2-cudnn9-runtime \
  --build-context monarch-wheels=dist \
  .

# Push so it's available to the kubernetes cluster.
# Either (a) push to a container registry so your cluster can access it.
# Might be slow based on your upload speed and the size of the container.
docker push $USER/monarch:latest
# Or (b) if you have a fully local kubernetes cluster you can change it to
# imagePullPolicy: Never in the manifest and it'll use the image locally. This
# is the fastest iteration speed.

# With podman + kind:
# Same build command, replace "docker" with "podman"
# Save image to archive
podman save localhost/$USER/monarch:local-tag -o /tmp/monarch-image
# Then push to your kind cluster for local dev:
KIND_EXPERIMENTAL_PROVIDER=podman kind load image-archive /tmp/monarch-image -n monarch-cluster

Then point your deployment at the new image. Make sure to prepend the registry you used for docker login, like ghcr.io or docker.io, and that you have pushed the image first.

Running examples

Check out the examples/ directory for demonstrations of how to use Monarch's APIs.

We'll be adding more examples as we stabilize and polish functionality!

Running tests

We have both Rust and Python unit tests. Rust tests are run with cargo-nextest and Python tests are run with pytest.

Rust tests

Important: Monarch's Rust code uses PyO3 to interface with Python, which means the Rust binaries need to link against Python libraries. Before running Rust tests, you need to have a Python environment activated (conda, venv, or uv):

# If using uv (recommended)
uv sync  # This creates and activates a virtual environment
uv run cargo nextest run  # Run tests within the uv environment

# Or if using conda
conda activate monarchenv
cargo nextest run

# Or if using venv
source .venv/bin/activate
cargo nextest run

Without an active Python environment, you'll get Python linking errors like:

error: could not find native static library `python3.12`, perhaps an -L flag is missing?

Installing cargo-nextest:

# We use cargo-nextest to run our tests, as they provide strong process isolation
# between every test.
# Here we install it from source, but you can instead use a pre-built binary described
# here: https://nexte.st/docs/installation/pre-built-binaries/
cargo install cargo-nextest --locked

cargo-nextest supports all of the filtering flags of "cargo test".

Python tests

# Install test dependencies (if not already installed via uv sync)
uv sync --extra test

# Run unit tests with uv
uv run pytest python/tests/ -v -m "not oss_skip"

# Or if using pip
pip install -e '.[test]'
pytest python/tests/ -v -m "not oss_skip"

Disabling flaky CI tests

If a test is consistently failing in OSS CI and needs to be temporarily disabled without a code change, open a GitHub issue on this repo with a title of the form:

DISABLED <test-name>

At the start of each CI run, scripts/fetch_disabled_tests.py fetches all open issues whose titles start with DISABLED and skips the named tests. Closing the issue re-enables the test on the next run.

Naming format:

  • Rust (cargo nextest): use the test name exactly as it appears in nextest output: <binary> <module::path::test_fn>, e.g. DISABLED hyperactor proc::tests::test_child_lifecycle
  • Python (pytest): use a test function name, full node ID, or structural node-ID prefix. For example, DISABLED test_my_function skips that function (including all parameterizations), while DISABLED python/tests/test_example.py skips the entire file.

Overriding skips locally

To run a test that is currently disabled via a GitHub issue, you can override the fetched skip lists by creating the files before running scripts/fetch_disabled_tests.py. The script will not overwrite files that already exist:

  • disabled_tests.txt — controls which Python tests are skipped. Create this file with only the tests you want to skip (or leave it empty to skip none).
  • .config/nextest-filter.txt — controls which Rust tests are skipped. Write a nextest filter expression here (e.g. all() to run all tests, or not (test(some_test)) to skip only specific ones).

For example, to run all tests locally regardless of open issues:

echo -n "" > disabled_tests.txt
echo "all()" > .config/nextest-filter.txt
uv run python scripts/fetch_disabled_tests.py   # will skip both writes
uv run pytest python/tests/ -v -m "not oss_skip"

License

Monarch is BSD-3 licensed, as found in the LICENSE file.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

torchmonarch-0.7.0.dev20260822-cp313-cp313-macosx_11_0_universal2.whl (70.8 MB view details)

Uploaded CPython 3.13macOS 11.0+ universal2 (ARM64, x86-64)

torchmonarch-0.7.0.dev20260822-cp312-cp312-macosx_11_0_universal2.whl (70.8 MB view details)

Uploaded CPython 3.12macOS 11.0+ universal2 (ARM64, x86-64)

torchmonarch-0.7.0.dev20260822-cp311-cp311-macosx_11_0_universal2.whl (70.8 MB view details)

Uploaded CPython 3.11macOS 11.0+ universal2 (ARM64, x86-64)

torchmonarch-0.7.0.dev20260822-cp310-cp310-macosx_11_0_universal2.whl (70.8 MB view details)

Uploaded CPython 3.10macOS 11.0+ universal2 (ARM64, x86-64)

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp313-cp313-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp313-cp313-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 11dd29f531997b9ab74f07b79b7e64276ff4f9e70992d8efc224663e574f977d
MD5 082f0e4b9d02e3dd5ff0918fd7ff4572
BLAKE2b-256 190925d84a32cbe18f6dbe901fb2ab0fb5a119287f265f8e7499376cfe1a0cac

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp313-cp313-manylinux2014_x86_64.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp313-cp313-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp313-cp313-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 57123e9082145dc9ab369696b5ceb54e554553792000bd513c2f987b3d9a438f
MD5 d2ba4fab380642b45ed2011bd2f01bdb
BLAKE2b-256 689690b5693402dbfb3d64d5cbe7b50aed6187e0395fe174a497b5020a8a9ad9

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp313-cp313-manylinux2014_aarch64.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp313-cp313-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp313-cp313-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 299a0358dad0ff2437d7861591c218d2357b7f83bad6cfe2beb996eab6df7cf9
MD5 03bd642aa5a0e577a6aaaec813cb4b0e
BLAKE2b-256 cce4320a8545e65a02eb54b3b4c412255bd18313342b57e625b55a1ed31f5634

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp313-cp313-macosx_11_0_universal2.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp312-cp312-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp312-cp312-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 547444bd30569973b42b16b300f995129b65d26d67138004ef0a96353e70d36f
MD5 b3ef6c65fe480b78c9540b6194e15f0f
BLAKE2b-256 004ffca9f2d85175c23dd2991f4b6c0a633da483544e78703a766bd2a531cf68

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp312-cp312-manylinux2014_x86_64.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp312-cp312-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp312-cp312-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 131c2716cfe1d860c3de12ca3a8643d1af1a5421829d7f994e64cbe2412a726e
MD5 a342c76a45e864223a15c856c896f51c
BLAKE2b-256 6b0da3de46dcdf39726099c1a74dccb50e0f6d475d1e5c434fbc93cd0e1125ec

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp312-cp312-manylinux2014_aarch64.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp312-cp312-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp312-cp312-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 e237442faa015ffed71537cceeead31a0702b33962987c9e1b1b6106c9d059b3
MD5 fc1a7722801db6f826cbd12526da8d54
BLAKE2b-256 9260e39e73540f4428f5400ac2986ba3c371405e629df69722bae369f25de6df

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp312-cp312-macosx_11_0_universal2.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp311-cp311-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp311-cp311-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d0748d52a3dff205715c828907d89b428d7bcf040c2ea5ce9d28ff56db4bccba
MD5 2f32c6372a6de996bfe9bcfdeae8bf7f
BLAKE2b-256 9743e7cc277bb3130d8d74c8c0e44879ad31db2cf9dd884a51cf9cce27c2cbd6

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp311-cp311-manylinux2014_x86_64.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp311-cp311-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp311-cp311-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 d300736970372c1de7efc756d90c4245a1373c7034b9ba9145807852dec6f088
MD5 e81c3661600fa44361580603f7501c73
BLAKE2b-256 962d74d6fad66f24774639ce35bd99a83690f6a2619da7fcedfb5a9c0b6d2b5f

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp311-cp311-manylinux2014_aarch64.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp311-cp311-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp311-cp311-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 40025bdca20824d89bb893cbf7ab52643cb89bd0a139f5fda1d34c3bfa007d47
MD5 3f10ecabc60758df8e4a27334ffda6b2
BLAKE2b-256 a481a2ceba15e8f1c0a0d15e8b24b19202c53711a1b94399d7f43e7d1c7004ca

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp311-cp311-macosx_11_0_universal2.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp310-cp310-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp310-cp310-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a521d1ac6451c1d6373e8b18b59a2c782947b2f49059fed204359994b4309aa2
MD5 9a1233e0260ca6354a51c3ce34c2b135
BLAKE2b-256 16f1cb2e352f186a3f61721de8ce06986fc1ecede09aa1cf8cd370c379550038

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp310-cp310-manylinux2014_x86_64.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp310-cp310-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp310-cp310-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 a2a627abd008a59fe860754f014c1c88953ac47f6122c5810ad5898683c43b73
MD5 e2cf6b13fb0a6ecea536c4601479edc6
BLAKE2b-256 756caffa9253d34256225e6a2afecf0ce99b34065f1006cf3536e35df96dc6e4

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp310-cp310-manylinux2014_aarch64.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file torchmonarch-0.7.0.dev20260822-cp310-cp310-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for torchmonarch-0.7.0.dev20260822-cp310-cp310-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 f0b0aa4233f2c9136c0da1e42de08d16f01c05515ded3555c265dcdb362cccf8
MD5 4da8b521d1be2b829f2eeb0366a71c9f
BLAKE2b-256 2fa31f5504f70dc33a1fda707056052b128050cbc2f06788ca7a9f931c14e99e

See more details on using hashes here.

Provenance

The following attestation bundles were made for torchmonarch-0.7.0.dev20260822-cp310-cp310-macosx_11_0_universal2.whl:

Publisher: wheels.yml on meta-pytorch/monarch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.7.0.dev20260822 This release

12 files

0.6.0

12 files

0.5.0

12 files

0.4.1

8 files

0.4.0

8 files

0.3.0

4 files

0.2.0

4 files

0.1.2

4 files

0.1.1

4 files

0.0.0

4 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page