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:
- Remote actors with scalable messaging: Actors are grouped into collections called meshes and messages can be broadcast to all members.
- 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.
- Point-to-point RDMA transfers: cheap registration of any GPU or CPU memory in a process, with the one-sided transfers based on libibverbs
- 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.
⚠️ Early Development Warning Monarch is currently in an experimental stage. You should expect bugs, incomplete features, and APIs that may change in future versions. The project welcomes bugfixes, but to make sure things are well coordinated you should discuss any significant change before starting the work. It's recommended that you signal your intention to contribute in the issue tracker, either by filing a new issue or by claiming an existing one.
📖 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:
Stable
pip install torchmonarch
Nightly
pip install --pre torchmonarch
Or install a specific nightly version:
pip install torchmonarch==0.3.0.dev20260106
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-cu128 index (CUDA 12.8). To use a different CUDA version:
- Edit
[tool.uv.sources]inpyproject.tomlto point to a different index (e.g.,pytorch-cu126,pytorch-cu130, orpytorch-cpu) - Or use
--extra-index-urlwhen running uv:uv sync --extra-index-url https://download.pytorch.org/whl/cu126
Understanding Tensor Engine
Monarch includes
distributed tensor
and
RDMA
APIs. Since these are hardware-specific, it can be useful to develop with a
lighter-weight version of Monarch (actors only) by setting
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
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-12-8 cuda-12-8
# 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-12-8 cuda-12-8
# 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.
Note that this does not support tensor_engine, which requires CUDA and RDMA libraries.
# 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 (without tensor_engine)
git clone https://github.com/meta-pytorch/monarch.git
cd monarch
# 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')"
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 .
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 the test function name, e.g.
DISABLED test_my_function
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, ornot (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.
6 maintainers
Metadata
6 maintainers
Release files for torchmonarch 0.5.0.dev20260401
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 663.1 MB
Release files / torchmonarch-0.5.0.dev20260401-cp313-cp313-manylinux2014_x86_64.whl
| Download URL | torchmonarch-0.5.0.dev20260401-cp313-cp313-manylinux2014_x86_64.whl |
|---|---|
| Size | 80.9 MB |
| Tags | CPython 3.13 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
0b593eaea2b77f34083219ab2c89976db8ae4f14918286a7e5aaf02dabfd3db8
|
|
BLAKE2b-256 checksum How to use checksums |
3474fbe059ba0799de62f7f25ddea6848b8938889249e264cebcc27fa504c852
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.
Transparency logRelease files / torchmonarch-0.5.0.dev20260401-cp313-cp313-manylinux2014_aarch64.whl
| Download URL | torchmonarch-0.5.0.dev20260401-cp313-cp313-manylinux2014_aarch64.whl |
|---|---|
| Size | 84.9 MB |
| Tags | CPython 3.13 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
a27737efd9c33e483c04296421900e286e6d97ad7ee9cc3b22d27b083c838a12
|
|
BLAKE2b-256 checksum How to use checksums |
e75dcbdb78ee422b07d8a8e90f1762ae62d4779c6894f0c38cb2d60969c2fd70
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.
Transparency logRelease files / torchmonarch-0.5.0.dev20260401-cp312-cp312-manylinux2014_x86_64.whl
| Download URL | torchmonarch-0.5.0.dev20260401-cp312-cp312-manylinux2014_x86_64.whl |
|---|---|
| Size | 80.9 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
0c9654602930f38bf3724453de6fd33664ec4224dcde6e932a7c068fa4344e5b
|
|
BLAKE2b-256 checksum How to use checksums |
7b6c3ab92d3ca3af212bf0915017f41bc76a98d0445e8f7f3c8ff5d6051fece6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.
Transparency logRelease files / torchmonarch-0.5.0.dev20260401-cp312-cp312-manylinux2014_aarch64.whl
| Download URL | torchmonarch-0.5.0.dev20260401-cp312-cp312-manylinux2014_aarch64.whl |
|---|---|
| Size | 84.9 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
cdd540ed36951da593d1e694d1507b09f23629821c55c7e242c9899cc03ed7d4
|
|
BLAKE2b-256 checksum How to use checksums |
570a398d3015fe97ab5d1cce772cd244c6c59c9d4434bb8560d8e5c1e5322b09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.
Transparency logRelease files / torchmonarch-0.5.0.dev20260401-cp311-cp311-manylinux2014_x86_64.whl
| Download URL | torchmonarch-0.5.0.dev20260401-cp311-cp311-manylinux2014_x86_64.whl |
|---|---|
| Size | 80.9 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
19b25fccc0f0114a146c7b90d9f3cf3fec0e91f427271e5d11e3e5e41ae756fb
|
|
BLAKE2b-256 checksum How to use checksums |
531a37aa5fd9b70d897eb431aef760e40745961dff56cdfab9856859c407b43d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.
Transparency logRelease files / torchmonarch-0.5.0.dev20260401-cp311-cp311-manylinux2014_aarch64.whl
| Download URL | torchmonarch-0.5.0.dev20260401-cp311-cp311-manylinux2014_aarch64.whl |
|---|---|
| Size | 84.8 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
72258c1a836a73eb60ee3fbf4678742b03ee7170d5fef4d3714d7ffd9274e1de
|
|
BLAKE2b-256 checksum How to use checksums |
f8135aa4822749a1fed86307e3607a892c20236c62197dba6f6fcccb2639b68d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.
Transparency logRelease files / torchmonarch-0.5.0.dev20260401-cp310-cp310-manylinux2014_x86_64.whl
| Download URL | torchmonarch-0.5.0.dev20260401-cp310-cp310-manylinux2014_x86_64.whl |
|---|---|
| Size | 80.9 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
c20c3b7dbe90d58c76d18159fad288c7b241c8e2ae9c6cc466764f0e10d9b114
|
|
BLAKE2b-256 checksum How to use checksums |
4f785ba4706cf8ba61c32ca52f0c36b7b8c447dd882006fabb284477b2ab265b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.
Transparency logRelease files / torchmonarch-0.5.0.dev20260401-cp310-cp310-manylinux2014_aarch64.whl
| Download URL | torchmonarch-0.5.0.dev20260401-cp310-cp310-manylinux2014_aarch64.whl |
|---|---|
| Size | 84.9 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
5f4d66a78cd578ac23a6d1d93a9574dc5343736db87e5ae3060d88b5008292dc
|
|
BLAKE2b-256 checksum How to use checksums |
8def9cff86ebd6461d2c0b99b853cb814cf3e6976d26cebf70959037aa159e4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 1, 2026.
Transparency log
