Description

# Pinecone Python SDK  [](https://github.com/pinecone-io/pinecone-python-client/actions/workflows/on-merge.yaml) [](https://pypi.org/project/pinecone/) [](https://www.python.org/downloads/) The official Pinecone Python SDK for building vector search applications with AI/ML. Pinecone is a vector database that makes it easy to add vector search to production applications. Use Pinecone to store, search, and manage high-dimensional vectors for applications like semantic search, recommendation systems, and RAG (Retrieval-Augmented Generation). ## Features - **Vector Operations**: Store, query, and manage high-dimensional vectors with metadata filtering - **Serverless & Pod Indexes**: Choose between serverless (auto-scaling) or pod-based (dedicated) indexes - **Integrated Inference**: Built-in embedding and reranking models for end-to-end search workflows - **Async Support**: Full asyncio support with `PineconeAsyncio` for modern Python applications - **GRPC Support**: Optional GRPC transport for improved performance - **Type Safety**: Full type hints and type checking support ## Table of Contents - [Documentation](#documentation) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Quickstart](#quickstart) - [Bringing your own vectors](#bringing-your-own-vectors-to-pinecone) - [Bring your own data using Pinecone integrated inference](#bring-your-own-data-using-pinecone-integrated-inference) - [Pinecone Assistant](#pinecone-assistant) - [More Information](#more-information-on-usage) - [Issues & Bugs](#issues--bugs) - [Contributing](#contributing) ## Documentation - [**Conceptual docs and guides**](https://docs.pinecone.io) - [**Python Reference Documentation**](https://sdk.pinecone.io/python/index.html) ### Upgrading the SDK > [!NOTE] > The official SDK package was renamed from `pinecone-client` to `pinecone` beginning in version `5.1.0`. > Please remove `pinecone-client` from your project dependencies and add `pinecone` instead to get > the latest updates. For notes on changes between major versions, see [Upgrading](./docs/upgrading.md) ## Prerequisites - The Pinecone Python SDK requires Python 3.10 or greater. It has been tested with CPython versions from 3.10 to 3.13. - Before you can use the Pinecone SDK, you must sign up for an account and find your API key in the Pinecone console dashboard at [https://app.pinecone.io](https://app.pinecone.io). ## Installation The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. The base installation includes everything you need to get started with vector operations, but you can install optional extras to unlock additional functionality. **Base installation includes:** - Core Pinecone client (`Pinecone`) - Vector operations (upsert, query, fetch, delete) - Index management (create, list, describe, delete) - Metadata filtering - Pinecone Assistant plugin **Optional extras:** - `pinecone[asyncio]` - Adds `aiohttp` dependency and enables `PineconeAsyncio` for async/await support. Use this if you're building applications with FastAPI, aiohttp, or other async frameworks. - `pinecone[grpc]` - Adds `grpcio` and related libraries for GRPC transport. Provides modest performance improvements for data operations like `upsert` and `query`. See the guide on [tuning performance](https://docs.pinecone.io/docs/performance-tuning). **Configuration:** The SDK can read your API key from the `PINECONE_API_KEY` environment variable, or you can pass it directly when instantiating the client. #### Installing with pip ```shell # Install the latest version pip3 install pinecone # Install the latest version, with optional dependencies pip3 install "pinecone[asyncio,grpc]" ``` #### Installing with uv [uv](https://docs.astral.sh/uv/) is a modern package manager that runs 10-100x faster than pip and supports most pip syntax. ```shell # Install the latest version uv add pinecone # Install the latest version, optional dependencies uv add "pinecone[asyncio,grpc]" ``` #### Installing with [poetry](https://python-poetry.org/) ```shell # Install the latest version poetry add pinecone # Install the latest version, with optional dependencies poetry add pinecone --extras asyncio --extras grpc ``` ## Quickstart ### Bringing your own vectors to Pinecone This example shows how to create an index, add vectors with embeddings you've generated, and query them. This approach gives you full control over your embedding model and vector generation process. ```python from pinecone import ( Pinecone, ServerlessSpec, CloudProvider, AwsRegion, VectorType ) # 1. Instantiate the Pinecone client # Option A: P