Pinecone Python SDK

The Pinecone Python SDK provides a client for the Pinecone vector database. Use it to create and manage indexes, upsert and query vectors, and run inference operations from Python.

Requires Python 3.10+.

Installation

pip install pinecone

For development dependencies (testing, type checking, linting):

pip install pinecone[dev]

Quick start

from pinecone import Pinecone, ServerlessSpec

# Initialize the client
pc = Pinecone(api_key="your-api-key")

# Create a serverless index
pc.indexes.create(
    name="movie-recommendations",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)

# Connect to the index
index = pc.index("movie-recommendations")

# Upsert vectors
index.upsert(
    vectors=[
        ("movie-42", [0.012, -0.087, 0.153]),  # 1536-dim embedding
        ("movie-87", [0.045, 0.021, -0.064]),  # 1536-dim embedding
    ],
    namespace="movies-en",
)

# Query for similar vectors
results = index.query(
    vector=[0.012, -0.087, 0.153],  # 1536-dim embedding
    top_k=10,
    namespace="movies-en",
)

for match in results.matches:
    print(f"{match.id}: {match.score:.4f}")

Async usage

The SDK provides an async client for use with asyncio:

import asyncio
from pinecone import AsyncPinecone

async def main():
    async with AsyncPinecone(api_key="your-api-key") as pc:
        desc = await pc.indexes.describe("movie-recommendations")
        index = pc.index(host=desc.host)
        async with index:
            results = await index.query(
                vector=[0.012, -0.087, 0.153],  # 1536-dim vector
                top_k=10,
                namespace="movies-en",
            )
            for match in results.matches:
                print(f"{match.id}: {match.score:.4f}")

asyncio.run(main())

Configuration

API key

Pass the API key directly or set the PINECONE_API_KEY environment variable:

from pinecone import Pinecone

# Explicit API key
pc = Pinecone(api_key="your-api-key")

# From environment variable (PINECONE_API_KEY)
pc = Pinecone()

Custom host

Connect to a specific control plane host:

pc = Pinecone(api_key="your-api-key", host="https://api.pinecone.io")

Timeout

Configure request timeouts in seconds:

pc = Pinecone(api_key="your-api-key", timeout=30)

Debug logging

Enable debug logging by setting the PINECONE_DEBUG environment variable:

export PINECONE_DEBUG=1

Development

Setup

Clone the repository and install dependencies with uv:

uv sync

Tests

uv run pytest tests/unit/ -x -v

Type checking

uv run mypy --strict pinecone/

Linting and formatting

uv run ruff check --fix
uv run ruff format

License

Apache-2.0. See LICENSE for details.