---
title: Studios SDK tutorial
description: >-
  A Studio is a persistent Lightning AI development environment. Use a Studio
  for
canonical: 'https://lightning.ai/docs/sdk/stable/examples/studios'
---
# Studios SDK tutorial {#studios-sdk-tutorial}

A Studio is a persistent Lightning AI development environment. Use a Studio for
interactive work, dependency setup, exploratory runs, and as a reusable runtime
for jobs or MMT runs. Starting a Studio attaches compute. Stopping a Studio
releases compute while preserving the Studio resource.

## Prerequisites {#prerequisites}

Install and authenticate:

```console
$ pip install lightning-sdk -U
$ lightning login
```

The SDK gives you a Python object that can start compute, execute commands, and
transfer files. The executable script stops the Studio after any optional
commands complete:

```python
teamspace = Teamspace(args.teamspace, org=args.org, user=args.user)

studio = Studio(
    name=args.studio,
    teamspace=teamspace,
    create_ok=True,
)

studio.start(machine=Machine.from_str(args.machine))
print(f"{studio.name} is {studio.status} on {studio.machine}")

output = studio.run("python --version")
print(output)

studio.upload_file(args.train_file, remote_path="train.py")
train_output = studio.run("python train.py --epochs 1")
print(train_output)
```

Use `run_with_exit_code` when failure is part of the control flow and you do
not want a non-zero command to raise immediately. The companion script runs this
branch only when `--run-tests` is passed:

```python
if args.run_tests:
    output, exit_code = studio.run_with_exit_code("python -m pytest -q")
    print(output)
    if exit_code != 0:
        raise RuntimeError(f"Tests failed with exit code {exit_code}")
```

Use `run_and_detach` for background work where you only need early output and
the command should continue in the Studio. The companion script runs this branch
only when `--detach-training` is passed:

```python
if args.detach_training:
    output, exit_code = studio.run_and_detach(
        "python train.py --epochs 10",
        timeout=30,
        check_interval=5,
    )
    print(output)
    print(f"Initial exit code: {exit_code}")
```

Run the companion script directly when you want to execute the SDK example:

```console
$ python python/examples/studios.py --teamspace teamspace --org owner --studio sdk-tutorial-studio
$ python python/examples/studios.py --teamspace teamspace --org owner --studio sdk-tutorial-studio --run-tests
```

## Operational notes {#operational-notes}

- `Studio("name", teamspace=..., create_ok=True)` creates the Studio when it
  does not exist. Use `create_ok=False` when automation should fail instead of
  creating a new resource.
- `studio.start` is blocking while compute is provisioned.
- `studio.run` requires the Studio to be running and raises if the command
  exits non-zero.
- Jobs and MMTs can reuse a Studio environment, which is useful when the Studio
  contains dependencies, code, or secrets configured through Lightning.
- Stop Studios when you do not need active compute.

---

**Navigation**

- Parent: [Examples](/docs/sdk/2026.11.04/examples.md)