Python SDK

The Pinecone Python SDK is distributed on PyPI using the package name pinecone. By default, the pinecone package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality:

• pinecone[grpc] adds dependencies on grpcio and related libraries needed to run data operations such as upserts and queries over gRPC for a modest performance improvement.

• pinecone[asyncio] adds a dependency on aiohttp and enables usage of async methods for use with asyncio. For more details, see Asyncio support.

​

Requirements

The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13.

​

Install

To install the latest version of the Python SDK, run the following command:

# Install the latest version
pip install pinecone

# Install the latest version with gRPC extras
pip install "pinecone[grpc]"

# Install the latest version with asyncio extras
pip install "pinecone[asyncio]"

To install a specific version of the Python SDK, run the following command:

# Install a specific version
pip install pinecone==<version>

# Install a specific version with gRPC extras
pip install "pinecone[grpc]"==<version>

# Install a specific version with asyncio extras
pip install "pinecone[asyncio]"==<version>

To check your SDK version, run the following command:

pip show pinecone

​

Install the Pinecone Assistant Python plugin

To interact with Pinecone Assistant using the Python SDK, upgrade the client and install the pinecone-plugin-assistant package as follows:

pip install --upgrade pinecone pinecone-plugin-assistant

​

Upgrade

If you already have the Python SDK, upgrade to the latest version as follows:

# Upgrade to the latest version
pip install pinecone --upgrade

# Upgrade to the latest version with gRPC extras
pip install "pinecone[grpc]" --upgrade

# Upgrade to the latest version with asyncio extras
pip install "pinecone[asyncio]" --upgrade

​

Initialize

Once installed, you can import the library and then use an API key to initialize a client instance:

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

When creating an index, import the ServerlessSpec or PodSpec class as well:

from pinecone.grpc import PineconeGRPC as Pinecone
from pinecone import ServerlessSpec

pc = Pinecone(api_key="YOUR_API_KEY")

pc.create_index(
  name="example-index",
  dimension=1536,
  metric="cosine",
  spec=ServerlessSpec(
    cloud="aws",
    region="us-east-1"
  )
)

​

Proxy configuration

If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters:

• proxy_url: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup.
• proxy_headers: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The make_headers utility from urllib3 can be used to help construct the dictionary. Note: Not supported with Asyncio.
• ssl_ca_certs: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the certifi package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format).
• ssl_verify: SSL verification is enabled by default, but it is disabled when set to False. It is not recommened to go into production with SSL verification disabled.

from pinecone import Pinecone
import urllib3 import make_headers

pc = Pinecone(
    api_key="YOUR_API_KEY",
    proxy_url='https://your-proxy.com',
    proxy_headers=make_headers(proxy_basic_auth='username:password'),
    ssl_ca_certs='path/to/cert-bundle.pem'
)

​

Async requests

Pinecone Python SDK versions 6.0.0 and later provide async methods for use with asyncio. Asyncio support makes it possible to use Pinecone with modern async web frameworks such as FastAPI, Quart, and Sanic, and should significally increase the efficiency of running requests in parallel.

Use the PineconeAsyncio class to create and manage indexes and the IndexAsyncio class to read and write index data. To ensure that sessions are properly closed, use the async with syntax when creating PineconeAsyncio and IndexAsyncio objects.

# pip install "pinecone[asyncio]"
import asyncio
from pinecone import PineconeAsyncio, ServerlessSpec

async def main():
    async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc:
        if not await pc.has_index(index_name):
            desc = await pc.create_index(
                name="example-index",
                dimension=1536,
                metric="cosine",
                spec=ServerlessSpec(
                    cloud="aws",
                    region="us-east-1"
                ),
                deletion_protection="disabled",
                tags={
                    "environment": "development"
                }
            )

asyncio.run(main())