This release is a pre-release and may not be stable for production use.
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",
batch_size=100, # split larger inputs into parallel batches automatically
)
# 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 = await 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
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. Tests must not write into the checkout —
use tmp_path / tmp_path_factory if a test genuinely needs a file on disk. A test that
writes a tracked file both dirties every contributor's tree and, if anything compares
against that file, quietly rewrites the thing it is comparing against.
Cross-transport storm parity
tests/unit/_internal/test_storm_parity.py checks that the sync, async, and gRPC retry
paths disperse a thundering herd comparably — dispersion widths within 2x and request
amplifications within 1.5x of each other. It runs all three canonical storm scenarios
itself, in-process, via tests/unit/_internal/_storm_parity_scenarios.py; there are no
recorded metric files and nothing is a checked-in baseline.
It used to work differently: each transport's storm test wrote a
_storm_parity_metrics_*.json file into tests/unit/_internal/, and the parity test read
all three back. Those files were tracked, so every unit run dirtied them, and because the
gRPC producer collects after the parity consumer, the gRPC comparison always read the
previous run's value — a stale-value failure that the same run then overwrote, so it
disappeared on retry. Keep the metrics in-process; don't reintroduce the file handoff.
Retry/throttle smoke tests (opt-in)
A suite of live-API smoke tests verifies that the retry stack and AIMD adaptive concurrency hold up against real Pinecone rate limits. These are not run in normal CI because they require real credentials, create a live serverless index, and take 1–3 minutes per run.
Required environment variables:
| Variable | Description |
|---|---|
PINECONE_API_KEY |
A valid Pinecone API key |
PINECONE_RETRY_SMOKE |
Set to 1 to enable the smoke tests |
Running the smoke tests:
PINECONE_API_KEY=your-api-key PINECONE_RETRY_SMOKE=1 \
uv run pytest tests/integration/test_retry_smoke.py -x -v -s
Cost: Each run creates three serverless indexes, upserts ~100K vectors per index, then deletes all indexes. Total cost is under $3 per run.
When to run: Before any release that touches retry logic, HTTP transport, the AIMD
adaptive-concurrency limiter (pinecone._internal.adaptive), or the batch-upsert path.
The unit tests mock HTTP responses; this test catches divergence between the synthetic
model and real API behavior (e.g., 503 instead of 429).
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.
1 maintainer
Metadata
1 maintainer
Release files for pinecone 10.0.0rc1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pinecone-10.0.0rc1.tar.gz | 423.0 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| pinecone-10.0.0rc1-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| pinecone-10.0.0rc1-cp310-abi3-musllinux_1_2_x86_64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ x86-64 | Details |
| pinecone-10.0.0rc1-cp310-abi3-musllinux_1_2_aarch64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ ARM64 | Details |
| pinecone-10.0.0rc1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| pinecone-10.0.0rc1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| pinecone-10.0.0rc1-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
| pinecone-10.0.0rc1-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 22.3 MB
Release files / pinecone-10.0.0rc1.tar.gz
| Download URL | pinecone-10.0.0rc1.tar.gz |
|---|---|
| Size | 423.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
13002876c8b5b178f61960182c5d2ca79cdcba24b1c93abe8204eb9bf55e3e47
|
|
BLAKE2b-256 checksum How to use checksums |
abbd4f936e5c6e9c3a401cc78f13eee8e1702ad035813d5f07630a7f58f581c5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / pinecone-10.0.0rc1-cp310-abi3-win_amd64.whl
| Download URL | pinecone-10.0.0rc1-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
bdaeb22cd72995e17afe061e72ff0c89ecb1399bd5d7157827b1d10884c9b228
|
|
BLAKE2b-256 checksum How to use checksums |
7a8e123a8e708626ffe68c8d3898c742f8b69868da39e97f512ee8d3e6e29f2e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / pinecone-10.0.0rc1-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | pinecone-10.0.0rc1-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
5dc1729dd2fcf158309596e4fb46c08c87bbd0a2a746967116013bb4fe3d457d
|
|
BLAKE2b-256 checksum How to use checksums |
a1c5d3ba581deec42de5acc9a75d942ceb44093102c3ab3d4f7fdddb0e1b9075
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / pinecone-10.0.0rc1-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | pinecone-10.0.0rc1-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
172c9a7b19dab75ad60f7765a4d2ad0d822b84c7d9c7f79180871cbb76878f69
|
|
BLAKE2b-256 checksum How to use checksums |
6783a6fc15fd799c5825092653b96b24b995affc0983aa858bab59b52e9ffd51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / pinecone-10.0.0rc1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pinecone-10.0.0rc1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.2 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
dfdad785477762620d226efb408abc4b30b0d70ac15f5710e33d1a42ed9b4a13
|
|
BLAKE2b-256 checksum How to use checksums |
a1255c65cc26efcba85e412c3d4b3571561cad81c82536949ed812d70233a35d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / pinecone-10.0.0rc1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pinecone-10.0.0rc1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 3.2 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
e6b46f7ad9ed0bc086a99534f05861503bbccda8c0c1ab33c5dc32acaacb258d
|
|
BLAKE2b-256 checksum How to use checksums |
855cdfe77b65a2cd80d68d1a73f9ba7d98b09c0523c3e615d68fcc2e811850eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / pinecone-10.0.0rc1-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | pinecone-10.0.0rc1-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
70ce990522590452a4396b349881780af57c866d2a8e9334694042ad1a94aa88
|
|
BLAKE2b-256 checksum How to use checksums |
d617ab4cf98b6f279994c5a1b9daa26a9743b5fa20257dad444b70725e472d07
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / pinecone-10.0.0rc1-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | pinecone-10.0.0rc1-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
a31e0be1c2bd92c8d7fcd4f2e87e28b143a63c25042644bd9aa606c01cb42905
|
|
BLAKE2b-256 checksum How to use checksums |
ea3c352460545bb87b44e594759c16c522882e0a70944941cc1cfb632a270c41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency log
