Pinecone Python SDK

Common errors

• 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'.

• 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'.

• 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)'.

• 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)'.

• 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 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
  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

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)