> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need.

# Python SDK

The Python SDK, the `amp` package, lets your Python code work with Amp:

* **Query** Amp with SQL, and get the results as [Apache Arrow](https://arrow.apache.org) tables, Polars DataFrames, or
  pandas DataFrames. Arrow is the columnar format Amp sends results in.
* **Stream** a query's results as new blocks arrive.
* **Load** query results into another system, like PostgreSQL, Snowflake, or a data lake, all at once or continuously.
* **Manage** Amp through its [Admin API](/managing-amp/admin-api): register and deploy datasets, and watch their jobs.
* **Inspect** a dataset's tables and columns.

It works with an Amp you run yourself and with a [hosted
Amp](/get-started/choose-how-to-run-amp#connect-to-a-hosted-amp).

## Prerequisites

* **Python 3.12 or newer.** `python3 --version` prints the version you have. [uv](https://docs.astral.sh/uv/), a
  Python package manager, downloads a suitable Python for you if you don't have one.
* **Git**, to install the package from its repository.
* **Access to the `edgeandnode/amp-python` repository** on GitHub.
* **An Amp to connect to.** The examples in these pages use the Amp and the `acme/eth_mainnet` dataset from the
  [Quickstart](/get-started/quickstart), on your own machine.

## Installation

The package isn't on PyPI yet, so you install it from its Git repository, or from a clone of it. Never run
`pip install amp`: it installs an unrelated package that has the same name.

Install it into a virtual environment, which keeps a project's packages separate from the rest of your system. With
pip, create one and activate it first. With uv, create a project, which has its own:

:::code-group
```bash [pip]
python3 -m venv .venv
source .venv/bin/activate
pip install "amp @ git+https://github.com/edgeandnode/amp-python.git"
```

```bash [uv]
uv init --python 3.12 my-amp-project
cd my-amp-project
uv add "amp @ git+https://github.com/edgeandnode/amp-python.git"
```
:::

Either way, you get the latest commit of the repository's `main` branch. To pin a version instead, add `@` and a commit
or tag to the URL:

```bash
pip install "amp @ git+https://github.com/edgeandnode/amp-python.git@26729a057afcb03bf71d96b6236e45237e4c06de"
```

To install from a clone, for example to read the source or try a change, give the clone's path instead of the URL:

:::code-group
```bash [pip]
git clone https://github.com/edgeandnode/amp-python.git
pip install ./amp-python
```

```bash [uv]
git clone https://github.com/edgeandnode/amp-python.git
uv add ./amp-python
```
:::

The package includes everything to query Amp, stream, and use the Admin client. Some features need more
packages, which you install the same way, with `pip install` or `uv add`:

| Feature                                                        | Packages                                                                |
| -------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Results as pandas DataFrames                                   | `pandas`                                                                |
| Each [loader](/sdks/python/loaders#install-a-loaders-packages) | The destination's client library, like `psycopg2-binary` for PostgreSQL |

### Run the examples

Each example is a complete script. Save it in a file, like `query.py`, then run it with Python. With pip, keep your
virtual environment active (`source .venv/bin/activate` in each new terminal). With uv, run it through uv, from your
project's directory:

:::code-group
```bash [pip]
python query.py
```

```bash [uv]
uv run query.py
```
:::

The pages show the `python` form.

## Your first query

With the Quickstart's Amp running, this script gets the last five blocks of `acme/eth_mainnet`:

```python [query.py]
from amp import Client

client = Client('grpc://localhost:1602')

df = client.sql(
    'SELECT block_num, timestamp, gas_used FROM "acme/eth_mainnet".blocks ORDER BY block_num DESC LIMIT 5'
).to_polars()
print(df)
```

:::terminal
```bash
python query.py
```

```
shape: (5, 3)
┌───────────┬─────────────────────────┬──────────┐
│ block_num ┆ timestamp               ┆ gas_used │
│ ---       ┆ ---                     ┆ ---      │
│ u64       ┆ datetime[ns, UTC]       ┆ u64      │
╞═══════════╪═════════════════════════╪══════════╡
│ 24000099  ┆ 2025-12-13 00:25:59 UTC ┆ 10751338 │
│ 24000098  ┆ 2025-12-13 00:25:47 UTC ┆ 36233422 │
│ 24000097  ┆ 2025-12-13 00:25:35 UTC ┆ 52877862 │
│ 24000096  ┆ 2025-12-13 00:25:23 UTC ┆ 15967071 │
│ 24000095  ┆ 2025-12-13 00:25:11 UTC ┆ 21252932 │
└───────────┴─────────────────────────┴──────────┘
```
:::

* `Client` connects to Amp's query server, which answers SQL over [Arrow Flight](/querying/arrow-flight) on port 1602
  in solo mode.
* `client.sql()` prepares a query, and `to_polars()` runs it and returns its results as a Polars DataFrame.
* In SQL, a table is its dataset's name in double quotes, then the table's name: `"acme/eth_mainnet".blocks`.

[Querying](/sdks/python/querying) covers the other ways to get results.

## The client

`Client` is the entry point to everything the SDK does. It connects to up to two of Amp's services, each with its own
URL:

| Argument    | Service                                                                | Enables                                                                                        |
| ----------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `query_url` | The query server, over Arrow Flight, like `grpc://localhost:1602`      | Queries, streaming, and loaders. Required.                                                     |
| `admin_url` | The [Admin API](/managing-amp/admin-api), like `http://localhost:1610` | `client.datasets`, `client.jobs`, and `client.schema`: the [Admin client](/sdks/python/admin). |

The first positional argument is the query URL, so `Client('grpc://localhost:1602')` and
`Client(query_url='grpc://localhost:1602')` are the same. To also manage datasets:

```python
from amp import Client

client = Client(query_url='grpc://localhost:1602', admin_url='http://localhost:1610')
```

A hosted Amp's operator gives you its URLs and a token, which [Authentication](/sdks/python/authentication) explains how
to pass. Use `grpc+tls://` for a query server that uses TLS. [Client Reference](/sdks/python/reference/client) documents
every argument and method.

## What's next

* [Querying](/sdks/python/querying): results as Arrow, Polars, or pandas, batches for large results, and query plans.
* [Authentication](/sdks/python/authentication): connect to an Amp that requires a token.
* [Admin Client](/sdks/python/admin): register and deploy datasets from Python.
* [Inspecting Datasets](/sdks/python/inspecting-datasets): explore a dataset's tables.
* [Streaming](/sdks/python/streaming) and [Parallel Streaming](/sdks/python/parallel-streaming): follow the chain as it
  grows, and load long block ranges quickly.
* [Loaders](/sdks/python/loaders): load query results into databases and data lakes.
* [Labels](/sdks/python/labels): add your own data, like token names, to the rows you load.

## Troubleshooting

### `ERROR: Package 'amp' requires a different Python`

Your Python is older than 3.12. Install a newer one, then create the virtual environment again with it, like
`python3.12 -m venv .venv`. Or use uv, which downloads Python 3.12 for the project if you don't have it.

### `ModuleNotFoundError: No module named 'pandas'`

`to_pandas()` needs pandas, which the package doesn't install. Install it with `pip install pandas` or `uv add pandas`.

### `FlightUnavailableError` … `Connection refused`

Nothing answers at the query URL. Check that Amp is running, and that the URL's host and port are those of its query
server: 1602 in solo mode.