Registry / ai-ml / metaflow-torchrun

metaflow-torchrun

JSON →
library0.2.1pypypi✓ verified 83d ago

Metaflow-torchrun is a Python library that provides a `@torchrun` decorator to enable distributed PyTorch training within Metaflow steps. It abstracts away the complexities of launching and managing `torchrun` processes, allowing users to integrate distributed ML workflows seamlessly into their Metaflow flows. The current version is 0.2.1, with relatively frequent updates since its initial release.

pip install metaflow-torchrun
INSTALL
IMPORT
SIG · METAFLOW-TORCHRUN
M
metaflow-torchrun
ai-mlpythonv0.2.1
Install
42.5s avg
Import
Disk
7578MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
2/4 runs
✓ 44.5s
py 3.11
2/4 runs
✓ 43.5s
py 3.12
2/4 runs
✓ 40.68s
py 3.13
2/4 runs
✓ 41.45s
py 3.9
2/4 runs
2/4 runs
7578MB installed
● package 7578MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

torchrun
from metaflow_extensions import torchrun
from metaflow_torchrun import torchrun

This example demonstrates a basic Metaflow flow using the `@torchrun` decorator. Save this code as a Python file (e.g., `my_flow.py`) and run it from your terminal using `python my_flow.py run`. It will launch 2 parallel processes on the local machine within the `train_distributed` step, each printing its rank information. Ensure `metaflow-torchrun`, `metaflow`, and `torch` are installed in your environment.

import os import logging from metaflow import FlowSpec, step, current from metaflow_torchrun import torchrun # Set up basic logging to see output from torchrun logging.basicConfig(level=logging.INFO) class MyDistributedFlow(FlowSpec): @step def start(self): print(f"Starting flow {current.flow_name}...") self.next(self.train_distributed) # Decorate a step with @torchrun to enable distributed execution @torchrun(nproc_per_node=2) # Use 2 processes for illustration on a single node @step def train_distributed(self): # Inside a torchrun decorated step, the script is executed by multiple processes. # Each process will have environment variables like LOCAL_RANK, RANK, WORLD_SIZE. local_rank = int(os.environ.get("LOCAL_RANK", -1)) global_rank = int(os.environ.get("RANK", -1)) # RANK is the global rank world_size = int(os.environ.get("WORLD_SIZE", -1)) print(f"Hello from process {global_rank}/{world_size} (local rank {local_rank})\n" + f" in Metaflow run {current.run_id} step {current.step_name}.") # In a real scenario, you'd initialize a process group and run DDP here. # import torch.distributed as dist # if local_rank != -1: # dist.init_process_group("nccl" if torch.cuda.is_available() else "gloo", rank=global_rank, world_size=world_size) # Your PyTorch model training code... # if local_rank != -1: # dist.destroy_process_group() self.next(self.end) @step def end(self): print("Distributed training flow completed!") if __name__ == "__main__": # To run this flow: # 1. Save it as a Python file, e.g., `my_flow.py` # 2. Run from your terminal: `python my_flow.py run` # Ensure `metaflow-torchrun`, `metaflow`, and `torch` are installed. MyDistributedFlow()
Debug
Known issues
gotchaThe `@torchrun` decorator is incompatible with interactive notebooks (e.g., Jupyter), requiring Metaflow flows to be run from a standalone Python file.
fix
Run Metaflow flows decorated with `@torchrun` as a standalone Python script from your terminal: `python your_flow.py run`.
affects: >=0.1.0
gotchaEnsure `torch` is installed and `torchrun` is available in the Python environment where the Metaflow step executes.
fix
Install `torch` (which includes `torchrun`) in your environment: `pip install torch` (or `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` for CUDA-enabled versions).
affects: >=0.1.0
gotchaArguments intended for your PyTorch script, when passed to the `args` parameter of the `@torchrun` decorator, must be a list of strings.
fix
Pass arguments as `args=['--epochs', '10', '--lr', '0.01']` instead of a single string, dictionary, or other types. For example: `@torchrun(args=['--model-name', 'resnet50'])`.
affects: >=0.1.0
gotchaThe current implementation of `@torchrun` distributes processes across multiple GPUs/CPUs *on a single node*, not across multiple machines.
fix
Understand that `metaflow-torchrun` simplifies single-node distributed training. For multi-node setups, more advanced Metaflow features or other orchestrators would be required.
affects: >=0.1.0
Upgrade
Version history
0.2.1latest on PyPI · released Jan 28, 2026
Audit
Dependencies
metaflowrequiredCore MLOps framework that this library extends.
torchrequiredPyTorch library for distributed training, which includes `torchrun`.
Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources
metaflow-torchrun — pip install metaflow-torchrun · libregistry