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": {"your_vector": {"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", "your_vector": [0.1, 0.2, 0.3], "title": "Arrival"},
{"_id": "movie-002", "your_vector": [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="your_vector", 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.
Indexes created another way use other methods: an index created with the
deprecated top-level dimension=/metric= uses index.upsert / index.query, and
a legacy integrated index (pc.indexes.create_for_model(...)) uses
index.upsert_records / index.search. For new indexes that embed text for you,
give a document index a field with integrated embedding. See the
quickstart and the
documentation.
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="your_vector", values=[0.1, 0.2, 0.3])],
include_fields=["title"],
)
for doc in results.matches:
print(doc.id, doc.score)
asyncio.run(main())
Configuration
from pinecone import Pinecone
pc = Pinecone(
api_key="your-api-key", # or omit and set PINECONE_API_KEY
timeout=60, # request timeout in seconds; index handles inherit it
)
Setting PINECONE_DEBUG=1 before importing pinecone sets the pinecone logger
to DEBUG. The SDK installs no log handler, so configure one to see the output:
import logging
logging.basicConfig()
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.
Integration suites that hit a real backend are opt-in because they cost money;
each module documents its own gate. Before any release that touches retry logic, HTTP
transport, the AIMD adaptive-concurrency limiter, or the batch-upsert path, run
tests/integration/test_retry_smoke.py with PINECONE_API_KEY and
PINECONE_RETRY_SMOKE=1 set.
License
Apache-2.0. See LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for pinecone 10.2.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 | Provenance | |
|---|---|---|---|---|
| pinecone-10.2.0.tar.gz | 550.6 kB | With provenance | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| pinecone-10.2.0-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| pinecone-10.2.0-cp310-abi3-musllinux_1_2_x86_64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ x86-64 | Details |
| pinecone-10.2.0-cp310-abi3-musllinux_1_2_aarch64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ ARM64 | Details |
| pinecone-10.2.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.2.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| pinecone-10.2.0-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
| pinecone-10.2.0-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 23.5 MB
Release files / pinecone-10.2.0.tar.gz
| Download URL | pinecone-10.2.0.tar.gz |
|---|---|
| Size | 550.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
747d646579db7315fc5a6689336d9d22406c2674163d02c511d5fb39ab1d7744
|
|
BLAKE2b-256 checksum How to use checksums |
f1a2ca569e4885680a38955c21742efc2fd5a9087c59acbc5d1349c569f93ec4
|
| 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 Oct 23, 2026.
Transparency logRelease files / pinecone-10.2.0-cp310-abi3-win_amd64.whl
| Download URL | pinecone-10.2.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
b09a4eb11df6fdf50fb825f2f6f2bcd6dce6bfdaeab09c683e48d7a98c4fd339
|
|
BLAKE2b-256 checksum How to use checksums |
a2f6cec6f8efaa1e30e17ecbd6fd02094980b1ec650b98ed6569d4416e6dd304
|
| 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 Oct 23, 2026.
Transparency logRelease files / pinecone-10.2.0-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | pinecone-10.2.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 |
4aeaa49cea93a0ac4ec754d9619b0c89bf5e151680b0e76445bfa2e47181b9ad
|
|
BLAKE2b-256 checksum How to use checksums |
b07e2024afc94a910a685456b8b00cc6060a3866860f03778929f9f7b0624df2
|
| 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 Oct 23, 2026.
Transparency logRelease files / pinecone-10.2.0-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | pinecone-10.2.0-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
62fefd39f6c04d24090db9a29f05ad03570618b93e77b194d576727537d4c794
|
|
BLAKE2b-256 checksum How to use checksums |
db9923ca15017b1bb404f533de8c2daae769330803fa8c7e9c91e595c0eb25c1
|
| 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 Oct 23, 2026.
Transparency logRelease files / pinecone-10.2.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pinecone-10.2.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 |
6b18f222f9d54a7310fc6c9d3a979d7531cc0e325fa18b6b1f5ad094e30ad48f
|
|
BLAKE2b-256 checksum How to use checksums |
800d9e2a3c5e24496912188df1242915a9d75832aff9ab43818ea27a596052da
|
| 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 Oct 23, 2026.
Transparency logRelease files / pinecone-10.2.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pinecone-10.2.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 |
445ef65017bbc38e94c0246e1a76ea318f51e997494d1072bcc7921a4c99fd73
|
|
BLAKE2b-256 checksum How to use checksums |
873ef646b2f2a59e5bd2b7d4fb6372d7b12a85b25758702758869546e717d3e5
|
| 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 Oct 23, 2026.
Transparency logRelease files / pinecone-10.2.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | pinecone-10.2.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 |
abcc0bd4b0f1a695b70049220ead80cc9ce3736d7c06708b9a21772ccf09294f
|
|
BLAKE2b-256 checksum How to use checksums |
b575c153c2df72c3046abcc96d03452a66c86414fe69f20469f222b059115ddc
|
| 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 Oct 23, 2026.
Transparency logRelease files / pinecone-10.2.0-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | pinecone-10.2.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 |
c597303da794a0b6c273f675b52fc8f2d071ba4bde79570600afea73c5d366bc
|
|
BLAKE2b-256 checksum How to use checksums |
9016bf37f769767576ce2704974b7b972a235d186ba56516bd3f5c9e65f80dca
|
| 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 Oct 23, 2026.
Transparency logSecurity for pinecone 10.2.0
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.
Full provenance
All 8 files in this release have been uploaded with provenance metadata.
Attestation for pinecone-10.2.0.tar.gz
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 Oct 23, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
