Getting Started

This guide takes you from installation to your first successful read. You need an Aerospike server or cluster that your machine can already reach. aerospike-py connects to that server; it does not start one for you.

1. Install the client

pip install aerospike-py

The package supports CPython 3.10 and later. PyPI provides prebuilt wheels for supported macOS, Linux, and Windows x64 platforms, so a normal installation does not require a local Rust or C toolchain.

2. Choose a seed address

Start with the host and service port of any reachable node:

config = {
    "hosts": [("127.0.0.1", 3000)],
}

Port 3000 is Aerospike's default service port. If your container, Kubernetes Service, or remote cluster exposes a different address, replace both values with the address your application can reach.

Why only one address?

A seed is the first node the client contacts. After connecting, the client discovers the other nodes and keeps the cluster view up to date. Production configurations can list more than one seed for startup resilience.

3. Write and read one record

Choose the API that matches your application. Both clients use the same key, record, and policy types.

Sync

from aerospike_py import Client

config = {"hosts": [("127.0.0.1", 3000)]}
key = ("test", "users", "ada")

with Client(config).connect() as client:
    client.put(key, {"name": "Ada", "active": True})
    record = client.get(key)
    print(record.bins)

Async

import asyncio
from aerospike_py import AsyncClient

config = {"hosts": [("127.0.0.1", 3000)]}
key = ("test", "users", "ada")

async def main() -> None:
    async with AsyncClient(config) as client:
        await client.connect()
        await client.put(key, {"name": "Ada", "active": True})
        record = await client.get(key)
        print(record.bins)

asyncio.run(main())

Expected output:

{'name': 'Ada', 'active': True}

The key has three parts: namespace (test), set (users), and user key (ada). Aerospike stores the values in named bins. record.bins contains those values, while record.meta contains metadata such as generation and TTL.

4. Update and clean up

Sync

with Client(config).connect() as client:
    client.increment(key, "login_count", 1)
    updated = client.get(key)
    print(updated.bins)
    client.remove(key)

Async

async with AsyncClient(config) as client:
    await client.connect()
    await client.increment(key, "login_count", 1)
    updated = await client.get(key)
    print(updated.bins)
    await client.remove(key)

Where to go next

If you want to…	Read…
Set timeouts, pools, and multiple seeds	Client configuration
Understand records and read policies	Read operations
Use TTL, generation checks, or batch writes	Write operations
Handle failures by exception type	Error handling
Run secondary-index queries	Query and scan
Add the async client to a web service	FastAPI integration
Check every public method and type	API reference