TorchX SDK and Components

2026.4.30 verified Fri May 01 auth: no python

TorchX is a Python SDK and set of components for building and launching distributed PyTorch applications. It provides a unified API to run jobs across different schedulers (local, Slurm, Kubernetes, AWS Batch, etc.). Version 2026.4.30 is a nightly release. Release cadence is nightly (torchx-nightly) vs stable (torchx) using semver.

pip install torchx-nightly

Common errors

error ModuleNotFoundError: No module named 'torchx.runner' ↓

cause You are using an older version of torchx (<0.6.0) or using the wrong import path.

fix

For torchx >=0.6.0, use from torchx.runner import run. For older versions, use from torchx import run.

error ImportError: cannot import name 'get_scheduler_factories' from 'torchx.runtime' ↓

cause The function moved to torchx.schedulers in version 0.5.0.

fix

Use from torchx.schedulers import get_scheduler_factories.

error TypeError: AppDef.__init__() got an unexpected keyword argument 'dist_role' ↓

cause The `dist_role` parameter was removed in version 0.7.0. Use `roles` parameter instead.

fix

Replace dist_role=... with a Role object in the roles list.

error torchx.schedulers.api.SchedulerNotFoundError: No scheduler factory found for 'local' ↓

cause You are using an invalid scheduler name. The local scheduler is named 'local_cwd' or 'local_docker'.

fix

Use scheduler = TorchX.scheduler('local_cwd') or 'local_docker'.

Warnings

breaking In version 0.6.0, the `run` function moved from `torchx` to `torchx.runner`. Old code using `from torchx import run` will break. ↓

fix Use `from torchx.runner import run` instead.

breaking In version 0.5.0, scheduler factories were moved from `torchx.runtime` to `torchx.schedulers`. Imports from the old path will fail. ↓

fix Use `from torchx.schedulers import get_scheduler_factories`.

gotcha The nightly package `torchx-nightly` can conflict with the stable `torchx` package. Installing both can cause import errors. ↓

fix Use a virtual environment and install only one: either `torchx` (stable) or `torchx-nightly` (unstable).

gotcha TorchX requires PyTorch >= 1.11. If not installed, you'll get ImportError on torchx installation. ↓

fix Install PyTorch separately via `pip install torch` (or the appropriate variant for your system).

deprecated The `AppDef` constructor argument `dist_role` is deprecated as of 0.7.0. Use the new `Role` API instead. ↓

fix Define roles explicitly using `Role` objects and pass them to `AppDef(roles=[...])`.

gotcha When using `local_cwd` scheduler, the working directory is the current directory. If job artifacts or data are relative, they may not be found. ↓

fix Use absolute paths or set `workspace` in the TorchX config.

gotcha For remote schedulers (Kubernetes, Slurm) you need additional dependencies like `torchx[kubernetes]`. Missing them results in ModuleNotFoundError. ↓

fix Install extra dependencies: `pip install torchx[kubernetes]` or `torchx[slurm]`, etc.

Imports

TorchX
```
from torchx import TorchX
```
AppDef
```
from torchx.specs import AppDef
```
AppDef is now in specs module since 0.5.0

run

wrong

from torchx import run

correct

from torchx.runner import run

run moved to torchx.runner in 0.6.0

get_scheduler_factories

wrong

from torchx.runtime import get_scheduler_factories

correct

from torchx.schedulers import get_scheduler_factories

scheduler factories moved to schedulers module in 0.5.0

Quickstart

Create a simple AppDef and schedule it using the local (current working directory) scheduler.

import os
from torchx import TorchX
from torchx.specs import AppDef, Role

app = AppDef(
    name="test_job",
    roles=[
        Role(
            name="worker",
            image="pytorch/pytorch:latest",
            entrypoint="python",
            args=["-c", "import torch; print('hello')"],
            num_replicas=2,
        )
    ],
)
scheduler = TorchX.scheduler("local_cwd")
scheduler.schedule(app)
print("Job scheduled successfully")