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.
Install & Compatibility
Where this runs
tested against v9.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.13
11/15 runs
12/15 runs
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pinecone
✓ from pinecone import Pinecone
pc = Pinecone(api_key='YOUR_API_KEY')
✗ import pinecone
pinecone.init(api_key='YOUR_API_KEY', environment='us-east1-gcp')
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)
✓ pip install pinecone
✗ pip install pinecone-client
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.
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)
Debug
Known issues
breakingpinecone.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.fixReplace 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.
affects: < 3.0
breakingPackage 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.fixpip uninstall pinecone-client followed by pip install pinecone. Order matters — do not install both simultaneously.
affects: < 5.1.0
breakingPython 3.9 dropped in v8.0.0 (released Nov 2025). Python 3.9 reached EOL Oct 2, 2025.fixUpgrade to Python 3.10+.
affects: >= 8.0.0
breakingpinecone[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.fixUse the default REST client (pip install pinecone) unless gRPC is specifically needed. Isolate in a virtual environment if grpcio version conflicts occur.
affects: >= 4.0.0
gotchaServerless 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.fixCheck index type before applying configuration. Use pc.describe_index('name').spec to inspect whether the index is serverless or pod-based. affects: >= 3.0.0
gotchaIndex 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.fixPoll pc.describe_index('name').status.ready or use pc.create_index(..., timeout=-1) to block until ready before proceeding. affects: all
gotchaMetadata 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.fixFlatten metadata before upserting. Convert nested structures to strings or top-level keys. Validate metadata types before upsert calls.
affects: all
breakingInstalling 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).fixEnsure 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.
affects: all (for pinecone[grpc])
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pinecone'
The 'pinecone' package is not installed in the Python environment.
fixInstall the Pinecone package using pip: 'pip install pinecone'.
ImportError: cannot import name 'Pinecone' from 'pinecone'
Using an outdated version of the Pinecone SDK where the 'Pinecone' class is not available.
fixUpgrade the Pinecone SDK to the latest version: 'pip install pinecone --upgrade'.
AttributeError: module 'pinecone' has no attribute 'init'
Attempting to use the 'init' method, which is not present in newer versions of the Pinecone SDK.
fixUse the 'Pinecone' class for initialization: 'from pinecone import Pinecone; pc = Pinecone(api_key=api_key)'.
ImportError: cannot import name 'Client' from 'pinecone'
The 'Client' class has been removed or renamed in newer versions of the Pinecone SDK.
fixUse the 'Pinecone' class for client initialization: 'from pinecone import Pinecone; pc = Pinecone(api_key=api_key)'.
ImportError: cannot import name 'GRPCIndex' from 'pinecone'
The 'GRPCIndex' class has been removed or is not available in the current version of the Pinecone SDK.
fixEnsure you have the latest version of the Pinecone SDK installed: 'pip install pinecone --upgrade'.
Audit
Dependencies
urllib3requiredHTTP transport for REST client.
grpciooptionalOnly with pinecone[grpc] extra. Version-pinned — conflicts with other grpcio consumers in the same environment.
aiohttpoptionalOnly with pinecone[asyncio] extra.