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.
1 maintainer
Release files for pinecone 10.0.0
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.0.tar.gz | 525.1 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| pinecone-10.0.0-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| pinecone-10.0.0-cp310-abi3-musllinux_1_2_x86_64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ x86-64 | Details |
| pinecone-10.0.0-cp310-abi3-musllinux_1_2_aarch64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ ARM64 | Details |
| pinecone-10.0.0-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.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| pinecone-10.0.0-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
| pinecone-10.0.0-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 23.4 MB
Release files / pinecone-10.0.0.tar.gz
| Download URL | pinecone-10.0.0.tar.gz |
|---|---|
| Size | 525.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6066bbe9a7ae1d667cde08d262deb6fbea6feb35deb9177dd47141b55bbd9833
|
|
BLAKE2b-256 checksum How to use checksums |
a597f04b682e5d65d4cd09b76afd691f8834cf2c28d82bc942ad637a2c15c74d
|
| 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 Sep 3, 2026.
Transparency logRelease files / pinecone-10.0.0-cp310-abi3-win_amd64.whl
| Download URL | pinecone-10.0.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
2f4e3200ee3562d195802b363487dd7fe6039a8c13630fc25fa3e8726c7a8654
|
|
BLAKE2b-256 checksum How to use checksums |
bd5d93d123cfcf458ccc2defa4c0363be5fb7aabfcd375cd2414a3e944e7f55a
|
| 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 Sep 3, 2026.
Transparency logRelease files / pinecone-10.0.0-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | pinecone-10.0.0-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3ab0c843b4fb04fbac22f1b8455e389063208a50f6a95d7a90627939968198de
|
|
BLAKE2b-256 checksum How to use checksums |
7fa411795c174225b9dea5054618c91b956d0a26b3d7167a5d3531e167712e83
|
| 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 Sep 3, 2026.
Transparency logRelease files / pinecone-10.0.0-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | pinecone-10.0.0-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
0e05956a3201b1fbb54a1861277df919318a4941797f2d87fd558ac5ec232151
|
|
BLAKE2b-256 checksum How to use checksums |
04ef705e49608eac5803b9b55b6cfae2cac736c0395e709f7668f52c89afc99b
|
| 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 Sep 3, 2026.
Transparency logRelease files / pinecone-10.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pinecone-10.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
94d4c64779f3213a5cc538d3bd10a873da192cb9b0039db56690e556ba00b55c
|
|
BLAKE2b-256 checksum How to use checksums |
223550e23cac1d73c921b8cc2eb02c9ad2691f62e8b906db49237bcf85f90676
|
| 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 Sep 3, 2026.
Transparency logRelease files / pinecone-10.0.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pinecone-10.0.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
d482ed27a805cbd4aca2660da212008dd6e41d87d255279f405ff13b725970e2
|
|
BLAKE2b-256 checksum How to use checksums |
8a3e3b9dba42741ed8faf011d7bce8e1fd10f45dd0503e2888eceafa6be33424
|
| 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 Sep 3, 2026.
Transparency logRelease files / pinecone-10.0.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | pinecone-10.0.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
0994270c514b16c72ec94dd6c29ff2708b81d30ff8467e19de192a28a7c86b7e
|
|
BLAKE2b-256 checksum How to use checksums |
ec78d73c0aa1030931a1b28151c4ff727b793e443a4531521bc89a1d4c3124a0
|
| 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 Sep 3, 2026.
Transparency logRelease files / pinecone-10.0.0-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | pinecone-10.0.0-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
995c06e905940b10bb2aefe653225340b5a3f56f3efb373fe07f4e57b5043705
|
|
BLAKE2b-256 checksum How to use checksums |
0fc79d61f9a4adaaa6e315a0425c2127b449bda64633a9c50bc533ff71c0c894
|
| 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 Sep 3, 2026.
Transparency log
