Pinecone Python SDK

8.1.0 verified Tue May 12 auth: no python install: verified quickstart: verified

Official Python SDK for the Pinecone managed vector database service. Supports serverless and pod-based indexes, vector upsert/query/delete, metadata filtering, namespaces, and integrated inference (embedding + reranking). REST client by default; optional gRPC transport for performance. Async support via PineconeAsyncio. Package was renamed from pinecone-client to pinecone in v5.1.0.

pip install pinecone

Common errors

error ModuleNotFoundError: No module named 'pinecone' ↓

cause The 'pinecone' package is not installed in the Python environment.

fix

Install the Pinecone package using pip: 'pip install pinecone'.

error ImportError: cannot import name 'Pinecone' from 'pinecone' ↓

cause Using an outdated version of the Pinecone SDK where the 'Pinecone' class is not available.

fix

Upgrade the Pinecone SDK to the latest version: 'pip install pinecone --upgrade'.

error AttributeError: module 'pinecone' has no attribute 'init' ↓

cause Attempting to use the 'init' method, which is not present in newer versions of the Pinecone SDK.

fix

Use the 'Pinecone' class for initialization: 'from pinecone import Pinecone; pc = Pinecone(api_key=api_key)'.

error ImportError: cannot import name 'Client' from 'pinecone' ↓

cause The 'Client' class has been removed or renamed in newer versions of the Pinecone SDK.

fix

Use the 'Pinecone' class for client initialization: 'from pinecone import Pinecone; pc = Pinecone(api_key=api_key)'.

error ImportError: cannot import name 'GRPCIndex' from 'pinecone' ↓

cause The 'GRPCIndex' class has been removed or is not available in the current version of the Pinecone SDK.

fix

Ensure you have the latest version of the Pinecone SDK installed: 'pip install pinecone --upgrade'.

Warnings

breaking pinecone.init() removed in v3.0. Raises AttributeError on any v3+ install. Affects all pre-2024 tutorials, YouTube courses, LangChain/LlamaIndex integration examples, and most LLM-generated Pinecone code. ↓

fix Replace pinecone.init(api_key=..., environment=...) with pc = Pinecone(api_key=...). The environment parameter is gone for serverless — omit it. For pod indexes, environment is now passed inside PodSpec.

breaking Package renamed from pinecone-client to pinecone in v5.1.0. pinecone-client is now a frozen stub at v6.0.0. Having both installed causes import conflicts where the wrong version may be imported. ↓

fix pip uninstall pinecone-client followed by pip install pinecone. Order matters — do not install both simultaneously.

breaking Python 3.9 dropped in v8.0.0 (released Nov 2025). Python 3.9 reached EOL Oct 2, 2025. ↓

fix Upgrade to Python 3.10+.

breaking pinecone[grpc] had a breaking grpcio version bump in v4.0 to enable performance improvements. Environments with other grpcio consumers (e.g., TensorFlow, gRPC services) may see dependency conflicts. ↓

fix Use the default REST client (pip install pinecone) unless gRPC is specifically needed. Isolate in a virtual environment if grpcio version conflicts occur.

gotcha Serverless and pod indexes have different API surfaces. ServerlessSpec and PodSpec are not interchangeable. Attempting pod-only operations (e.g., configuring pod type, replicas) on a serverless index raises an API error. ↓

fix Check index type before applying configuration. Use pc.describe_index('name').spec to inspect whether the index is serverless or pod-based.

gotcha Index creation is asynchronous. pc.create_index() returns before the index is ready. Calling pc.Index('name') immediately after creation and then upsert/query may raise a 'not ready' or connection error. ↓

fix Poll pc.describe_index('name').status.ready or use pc.create_index(..., timeout=-1) to block until ready before proceeding.

gotcha Metadata values must be strings, numbers, booleans, or lists of strings. Nested dicts, None values, and lists of mixed types are silently dropped or cause an API validation error. ↓

fix Flatten metadata before upserting. Convert nested structures to strings or top-level keys. Validate metadata types before upsert calls.

breaking Installing pinecone[grpc] requires a C compiler (e.g., gcc) because some of its dependencies (like grpcio or lz4) rely on C extensions that need to be built during installation. This can lead to an 'error: command gcc failed' in environments lacking build tools, such as minimal Docker images (e.g., Alpine Linux). ↓

fix Ensure that development tools, including a C compiler, are installed in your environment before installing pinecone[grpc]. For Debian/Ubuntu, use 'apt-get install build-essential'. For Alpine Linux, use 'apk add alpine-sdk'. If gRPC is not strictly necessary, consider using the default REST client by installing 'pinecone' without the '[grpc]' extra.

Install

pip install 'pinecone[grpc]'

pip install 'pinecone[asyncio]'

pip uninstall pinecone-client && pip install pinecone

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) asyncio - - 0.28s 34.8M

3.10 alpine (musl) grpc - - 0.13s 34.8M

3.10 alpine (musl) pinecone - - 0.28s 33.2M

3.10 slim (glibc) asyncio - - 0.18s 35M

3.10 slim (glibc) grpc - - 0.18s 35M

3.10 slim (glibc) pinecone - - 0.18s 34M

3.11 alpine (musl) asyncio - - 0.44s 37.3M

3.11 alpine (musl) grpc - - 0.23s 37.3M

3.11 alpine (musl) pinecone - - 0.42s 36.5M

3.11 slim (glibc) asyncio - - 0.33s 38M

3.11 slim (glibc) grpc - - 0.33s 38M

3.11 slim (glibc) pinecone - - 0.35s 37M

3.12 alpine (musl) asyncio - - 0.46s 28.9M

3.12 alpine (musl) grpc - - 0.40s 28.9M

3.12 alpine (musl) pinecone - - 0.45s 27.9M

3.12 slim (glibc) asyncio - - 0.42s 29M

3.12 slim (glibc) grpc - - 0.45s 29M

3.12 slim (glibc) pinecone - - 0.46s 28M

3.13 alpine (musl) asyncio - - 0.46s 36.9M

3.13 alpine (musl) grpc - - - -

3.13 alpine (musl) pinecone - - 0.46s 27.4M

3.13 slim (glibc) asyncio - - 0.46s 39M

3.13 slim (glibc) grpc - - 0.48s 55M

3.13 slim (glibc) pinecone - - 0.48s 28M

3.9 alpine (musl) asyncio - - 0.30s 40.2M

3.9 alpine (musl) grpc - - - -

3.9 alpine (musl) pinecone - - 0.30s 31.0M

3.9 slim (glibc) asyncio - - 0.29s 43M

3.9 slim (glibc) grpc - - 0.28s 58M

3.9 slim (glibc) pinecone - - 0.28s 31M

Imports

Pinecone
wrong
```
import pinecone
pinecone.init(api_key='YOUR_API_KEY', environment='us-east1-gcp')
```
correct
```
from pinecone import Pinecone
pc = Pinecone(api_key='YOUR_API_KEY')
```
pinecone.init() removed in v3.0. The environment parameter is also gone — serverless indexes have no environment. Every tutorial and course before 2024 uses pinecone.init(). Raises AttributeError: module 'pinecone' has no attribute 'init'.
pinecone (package name)
wrong
```
pip install pinecone-client
```
correct
```
pip install pinecone
```
Package renamed from pinecone-client to pinecone in v5.1.0. pinecone-client is frozen at v6.0.0 (a stub that prints a deprecation warning). Having both installed simultaneously causes confusing import conflicts. Must pip uninstall pinecone-client before installing pinecone.

Quickstart verified last tested: 2026-05-12

v3+ uses object-oriented client. ServerlessSpec replaces the old environment string. Pod indexes use PodSpec instead.

from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key='YOUR_API_KEY')  # or set PINECONE_API_KEY env var

# Create serverless index
if not pc.has_index('my-index'):
    pc.create_index(
        name='my-index',
        dimension=1536,
        metric='cosine',
        spec=ServerlessSpec(cloud='aws', region='us-east-1'),
    )

index = pc.Index('my-index')

# Upsert vectors
index.upsert(vectors=[
    {'id': 'v1', 'values': [0.1] * 1536, 'metadata': {'source': 'doc1'}},
])

# Query
results = index.query(vector=[0.1] * 1536, top_k=5, include_metadata=True)
print(results)