Pinecone Python SDK

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.

Install

• pip install pinecone Base (REST client)
• pip install 'pinecone[grpc]' gRPC transport (modest perf improvement)
• pip install 'pinecone[asyncio]' Async support (PineconeAsyncio)
• pip uninstall pinecone-client && pip install pinecone Migration from old package name

Imports

• Pinecone

  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)

  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

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)