---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/sdks/python
markdown_url: https://steel.dev/docs/reference/sdks/python.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Python SDK
description: Install the Steel Python SDK, configure the client, and handle errors, retries, and pagination.
summary: Install the Steel Python SDK, configure the client, and handle errors, retries, and pagination.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/sdks/typescript.md
  - https://steel.dev/docs/reference/sdks/go.md
  - https://steel.dev/docs/reference/sdks/rust.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Python SDK

The Steel SDK for Python is the `steel-sdk` package on PyPI, imported as `steel`. It gives your code methods for the endpoints of the Steel API, and it retries failed requests and pages through lists for you. The [API reference](https://steel.dev/docs/reference/api) shows the call for each endpoint.

## Install

Install the SDK in a virtual environment. Then `python` and `pip` run the Python that has the SDK, even on macOS, which has no `python` command of its own. In each new terminal, run `source .venv/bin/activate` again.

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk
```

The SDK needs Python 3.10 or later. It has a synchronous client, `Steel`, and an asynchronous client, `AsyncSteel`, both built on [httpx](https://github.com/encode/httpx).

To use `aiohttp` instead of `httpx` in the asynchronous client, install the extra:

```sh
pip install 'steel-sdk[aiohttp]'
```

Then pass `http_client=DefaultAioHttpClient()` to `AsyncSteel`. Import `DefaultAioHttpClient` from `steel`.

## Create a client

`Steel()` reads your API key from the `STEEL_API_KEY` environment variable. To change the key or another setting, pass keyword arguments.

```python
from steel import Steel

client = Steel()
```

| Argument | Default | Meaning |
| - | - | - |
| `steel_api_key` | `STEEL_API_KEY` | The API key. The SDK sends it in the `steel-api-key` header. |
| `base_url` | `STEEL_BASE_URL`, then `https://api.steel.dev` | The URL of the API. Change it to use a [self-hosted Steel Browser](https://steel.dev/docs/self-hosting/steel-browser). |
| `timeout` | 60 seconds, 5 seconds to connect | How long one HTTP request can take. A number of seconds or an `httpx.Timeout`. |
| `max_retries` | `2` | How many times the SDK retries a request that failed. |
| `default_headers` | none | Headers to send with every request. |
| `default_query` | none | Query parameters to send with every request. |
| `http_client` | an `httpx` client | A custom `httpx.Client`, or `httpx.AsyncClient` for `AsyncSteel`. |

The `STEEL_CUSTOM_HEADERS` environment variable adds headers to every request. Write one `Name: value` pair on each line.

Set `STEEL_LOG` to `info` or `debug` to log requests with the standard `logging` module.

## Create a session

This program creates a session, prints its ID, and releases it. A session runs until you release it or until it times out, so release it in `finally`.

```python file=session.py
from steel import Steel

client = Steel()
session = client.sessions.create()

try:
    print(session.id)
finally:
    client.sessions.release(session.id)
```

Run the program:

```sh
python session.py
```

The program prints the session's ID.

```text nocopy
0128f557-f063-4db9-b97b-48092ee22e8e
```

To drive the session's browser, connect Playwright over CDP (Chrome DevTools Protocol). See [Playwright](https://steel.dev/docs/integrations/playwright).

A method's arguments are snake_case, such as `use_proxy` and `block_ads`. Nested parameters are dictionaries. Responses are Pydantic models, with `to_dict()` and `to_json()`. [Session configuration](https://steel.dev/docs/sessions/configuration) lists every option of a new session.

In `sessions.create`, the session timeout is `api_timeout`, in milliseconds. The `timeout` argument of any method is the HTTP timeout of that request.

> **Note**
>
> When `sessions.create` gets a number in `timeout` and no `api_timeout`, the SDK also sends that number as the session timeout. It emits a `DeprecationWarning`, because this use stops working in a future release. The same number is still the HTTP timeout of the request, in seconds. Use `api_timeout`.

The asynchronous client has the same methods. Use `await` with each call:

```python
import asyncio

from steel import AsyncSteel

client = AsyncSteel()


async def main() -> None:
    session = await client.sessions.create()
    try:
        print(session.id)
    finally:
        await client.sessions.release(session.id)


asyncio.run(main())
```

## Retries and timeouts

The SDK retries a request twice, with a short exponential backoff, after one of these failures:

- a connection error
- `408 Request Timeout`
- `409 Conflict`
- `429 Too Many Requests`
- a status of 500 or higher

When a response has the `x-should-retry` header, the SDK follows it instead of this list. `true` retries, and `false` does not.

A request times out after one minute and then raises `APITimeoutError`. The SDK retries a request that timed out, so a call can take longer than its timeout.

Set `max_retries` and `timeout` on the client for all requests:

```python
from steel import Steel

client = Steel(max_retries=0, timeout=20.0)
```

For a separate limit on each phase of the request, pass an `httpx.Timeout`:

```python
import httpx
from steel import Steel

client = Steel(timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0))
```

To change the retries or the timeout for one call, use `with_options`:

```python
client.with_options(max_retries=5, timeout=5.0).sessions.retrieve(session.id)
```

## Handle errors

All errors of the SDK inherit from `steel.APIError`.

- When the SDK cannot reach the API, it raises `steel.APIConnectionError`. A timeout raises `steel.APITimeoutError`, a subclass of it.
- When the API returns a 4xx or 5xx status, the SDK raises a subclass of `steel.APIStatusError`. It has `status_code`, `response` and `body`, which is the response's JSON body.

```python
import steel
from steel import Steel

client = Steel()

try:
    client.sessions.retrieve(session_id)
except steel.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)
except steel.RateLimitError:
    print("A 429 status code was received")
except steel.APIStatusError as e:
    print(e.status_code)
    print(e.body)
```

| Status | Error class |
| - | - |
| 400 | `BadRequestError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 409 | `ConflictError` |
| 422 | `UnprocessableEntityError` |
| 429 | `RateLimitError` |
| 500 or higher | `InternalServerError` |
| No response | `APIConnectionError` |

[Errors](https://steel.dev/docs/reference/errors) lists the error codes and messages of the API.

## Pagination

`client.sessions.list` returns its results in pages. Iterate over the result to read every item. The SDK fetches the next page when it needs it.

```python
for session in client.sessions.list(status="live"):
    print(session.id)
```

With `AsyncSteel`, use `async for`.

To read one page at a time, use `has_next_page()` and `get_next_page()`:

```python
page = client.sessions.list(status="live")
while True:
    for session in page.sessions:
        print(session.id)
    if not page.has_next_page():
        break
    page = page.get_next_page()
```

## Methods

Each group of methods matches a page of the API reference. The methods take the same parameters as the endpoints, in snake_case.

| Methods | API reference |
| - | - |
| `client.sessions`, `client.sessions.files`, `client.sessions.captchas` | [Sessions API](https://steel.dev/docs/reference/api/sessions) |
| `client.scrape`, `client.screenshot`, `client.pdf` | [Quick actions API](https://steel.dev/docs/reference/api/quick-actions) |
| `client.profiles` | [Profiles API](https://steel.dev/docs/reference/api/profiles) |
| `client.credentials` | [Credentials API](https://steel.dev/docs/reference/api/credentials) |
| `client.files` | [Files API](https://steel.dev/docs/reference/api/files) |
| `client.extensions` | [Extensions API](https://steel.dev/docs/reference/api/extensions) |
| `client.projects` | [Projects API](https://steel.dev/docs/reference/api/projects) |
| `client.api_keys` | [API keys API](https://steel.dev/docs/reference/api/api-keys) |

The SDK's own list of methods and types is [api.md](https://github.com/steel-dev/sdk/tree/main/python/api.md).
