TorchX SDK and Components

0.7.0 · active · verified Thu Apr 16

TorchX is a Python SDK for MLOps that helps you compose, configure, and launch PyTorch applications on various schedulers like local, Docker, Kubernetes, and Ray. It provides a common API for distributed training, serving, and other ML workloads. The current version is 0.7.0, with major releases occurring every few months.

Common errors

```
ModuleNotFoundError: No module named 'torchx.schedulers.ddp_scheduler'
```
cause The `ddp_scheduler` module was removed in TorchX v0.7.0.

fix Update your code to use `ray_scheduler` for DDP workloads, or use a general scheduler like Kubernetes with appropriate configurations. For example, `runner.run(app, scheduler='ray_scheduler')`.
```
Error: No such command 'run'
```
cause The `torchx run` CLI command was renamed to `torchx launch` in v0.6.0.

fix Replace `torchx run` with `torchx launch` in your command-line invocations.
```
TypeError: Role() got an unexpected keyword argument 'scheduler'
```
cause The `scheduler` argument was removed from `torchx.specs.Role` in v0.5.0.

fix Remove the `scheduler` argument from your `specs.Role` constructor. Specify the scheduler via `TorchxRunner.run(app, scheduler='...')` instead.
```
RuntimeError: Docker client is not available or daemon is not running. Please ensure docker is installed and running.
```
cause Attempting to use a Docker-based scheduler (e.g., `local_docker`) without a running Docker daemon.

fix Start the Docker daemon on your machine. For Linux, ensure the Docker service is running (`sudo systemctl start docker`). For Docker Desktop, ensure the application is open and running.

Warnings

breaking The `torchx.schedulers.ddp_scheduler` module was removed and replaced with the `ray_scheduler` for DDP-like workloads.
Fix: Migrate from `ddp_scheduler` to `ray_scheduler` or `kubernetes` scheduler for distributed training applications.
breaking The CLI command `torchx run` was renamed to `torchx launch`.
Fix: Update your CLI scripts to use `torchx launch` instead of `torchx run`.
breaking The `scheduler` field was removed from `specs.Role`. Scheduler selection now happens at the `runner.run()` level.
Fix: Remove the `scheduler` argument from `specs.Role` definitions. Pass the desired scheduler string directly to `TorchxRunner.run(app, scheduler='your_scheduler')`.
gotcha Using Docker-based schedulers (e.g., `local_docker`, `kubernetes` with container images) requires a running Docker daemon.
Fix: Ensure Docker Desktop or the Docker daemon is installed and actively running on your system before attempting to launch jobs with Docker-dependent schedulers.
gotcha TorchX components like `dist.ddp` are factory functions that return `AppDef` objects, not direct applications or classes.
Fix: When using components, pass their output directly to `runner.run()`, e.g., `runner.run(torchx.components.dist.ddp_torchscript(...), ...)` rather than trying to `import ddp` directly.

Install

pip install torchx Stable release

Imports

TorchxRunner
```
from torchx.runner import TorchxRunner
```
AppDef
```
from torchx.specs import AppDef
```
Role
```
from torchx.specs import Role
```
Resource
```
from torchx.specs import Resource
```
ddp
wrong:
```
from torchx.components import ddp
```
correct:
```
import torchx.components.dist.ddp
```
Components are typically accessed as submodules, e.g., `torchx.components.dist.ddp`.

Quickstart

This quickstart demonstrates how to define a basic `AppDef` with a single role and launch it using `TorchxRunner` on the `local_cwd` scheduler. It prints 'Hello, TorchX!' to the console via the `echo` command.

from torchx import specs
from torchx.runner import TorchxRunner

# Define a simple application
app = specs.AppDef(
    name='hello-world',
    roles=[
        specs.Role(
            name='worker',
            entrypoint='echo',
            args=['Hello, TorchX!'],
            num_replicas=1,
            resource=specs.Resource(cpu=1, memMB=512)
        )
    ]
)

# Initialize the TorchX runner
runner = TorchxRunner()

# Launch the application on the local_cwd scheduler
# Ensure you have a 'local_cwd' scheduler configured or just use 'local_cwd'
app_handle = runner.run(app, scheduler='local_cwd')
print(f"Application '{app.name}' launched with handle: {app_handle}")

# You can optionally wait for the application to complete
# runner.wait(app_handle, timeout=300) # Waits up to 5 minutes
# print(f"Application '{app.name}' completed.")

view raw JSON →