Development Status
- 5 - Production/Stable
Intended Audience
- Developers
- Information Technology
- Science/Research
- System Administrators
Operating System
- OS Independent
Programming Language
- Python :: 3.10
- Python :: 3.11
- Python :: 3.12
- Python :: 3.13
- Python :: 3.14
Topic
- Database
- Software Development
- Software Development :: Libraries
- Software Development :: Libraries :: Application Frameworks
- Software Development :: Libraries :: Python Modules
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 records, and run inference operations from Python.
Requires Python 3.10+.
Upgrading from 9.x? create and configure moved from spec=/dimension= to schema=/deployment=; see the v10 migration guide for the field-by-field mapping.
Installation
pip install pinecone
Quick start
An index declares its fields as a schema. Declaring a schema makes it a document
index: you read and write it through index.documents, and each record is a JSON
document whose fields you named yourself.
from pinecone import DenseVectorQuery, Pinecone
pc = Pinecone(api_key="your-api-key") # or omit and set PINECONE_API_KEY
# Create an index. This blocks until the index is ready.
pc.indexes.create(
name="movie-recommendations",
schema={"fields": {"embedding": {"type": "dense_vector", "dimension": 3, "metric": "cosine"}}},
deployment={"deployment_type": "managed", "cloud": "aws", "region": "us-east-1"},
)
# Get a data-plane handle for that index
index = pc.index("movie-recommendations")
# Upsert documents. Each one needs an `_id`; every other key is either a field
# you declared in the schema or arbitrary metadata.
index.documents.upsert(
namespace="movies-en",
documents=[
{"_id": "movie-001", "embedding": [0.1, 0.2, 0.3], "title": "Arrival"},
{"_id": "movie-002", "embedding": [0.4, 0.5, 0.6], "title": "Interstellar"},
],
)
# Search. `score_by` names the field to compare against.
results = index.documents.search(
namespace="movies-en",
top_k=5,
score_by=[DenseVectorQuery(field="embedding", values=[0.1, 0.2, 0.3])],
include_fields=["title"],
)
for doc in results.matches:
print(doc.id, doc.score)
Upserts apply asynchronously, so a document may not be visible to the next search immediately.
Two other data-plane interfaces exist, and the way the index was created decides
which one applies: an index created with the deprecated top-level vector
arguments answers on index.upsert / index.query, and one created with
pc.indexes.create_for_model(...) embeds text server-side and answers on
index.upsert_records / index.search. See the
quickstart and
the rest of the documentation for the full
picture.
Async usage
The SDK provides an async client for use with asyncio. Its index() is a
coroutine, and the handle it returns is a context manager:
import asyncio
from pinecone import AsyncPinecone, DenseVectorQuery
async def main():
async with AsyncPinecone(api_key="your-api-key") as pc:
index = await pc.index("movie-recommendations")
async with index:
results = await index.documents.search(
namespace="movies-en",
top_k=5,
score_by=[DenseVectorQuery(field="embedding", values=[0.1, 0.2, 0.3])],
include_fields=["title"],
)
for doc in results.matches:
print(doc.id, doc.score)
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
Clone the repository and install the dev dependency group with uv, which is what CI does:
uv sync --group dev
uv run pytest tests/unit/ -x -v # tests
uv run mypy --strict pinecone/ # type checking
uv run ruff check --fix # linting
uv run ruff format # formatting
The unit suite must leave the working tree clean: git status is expected to report
no changes after a bare uv run pytest tests/unit. Use tmp_path /
tmp_path_factory if a test genuinely needs a file on disk.
Some suites are opt-in because they hit a real backend and cost money. The live
retry/throttle smoke tests in tests/integration/test_retry_smoke.py need
PINECONE_API_KEY plus PINECONE_RETRY_SMOKE=1; run them before any release that
touches retry logic, HTTP transport, the AIMD adaptive-concurrency limiter, or the
batch-upsert path. Each module documents its own gate and cost.
License
Apache-2.0. See LICENSE for details.
Wheel compatibility matrix
Files in release
httpx[http2]
(<1.0,>=0.27)
msgspec
(<0.22,>=0.19)
orjson
(<4,>=3.11)
anyio
(>=4.0)