{"id":61,"library":"pinecone","title":"Pinecone Python SDK","description":"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.","status":"active","version":"8.1.0","language":"python","source_language":"en","source_url":"https://docs.pinecone.io","tags":["pinecone","vector-database","managed","serverless","rag","similarity-search","embeddings","cloud"],"install":[{"cmd":"pip install pinecone","lang":"bash","label":"Base (REST client)"},{"cmd":"pip install 'pinecone[grpc]'","lang":"bash","label":"gRPC transport (modest perf improvement)"},{"cmd":"pip install 'pinecone[asyncio]'","lang":"bash","label":"Async support (PineconeAsyncio)"},{"cmd":"pip uninstall pinecone-client && pip install pinecone","lang":"bash","label":"Migration from old package name"}],"dependencies":[{"reason":"HTTP transport for REST client.","package":"urllib3","optional":false},{"reason":"Only with pinecone[grpc] extra. Version-pinned — conflicts with other grpcio consumers in the same environment.","package":"grpcio","optional":true},{"reason":"Only with pinecone[asyncio] extra.","package":"aiohttp","optional":true}],"imports":[{"note":"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'.","wrong":"import pinecone\npinecone.init(api_key='YOUR_API_KEY', environment='us-east1-gcp')","symbol":"Pinecone","correct":"from pinecone import Pinecone\npc = Pinecone(api_key='YOUR_API_KEY')"},{"note":"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.","wrong":"pip install pinecone-client","symbol":"pinecone (package name)","correct":"pip install pinecone"}],"quickstart":{"code":"from pinecone import Pinecone, ServerlessSpec\n\npc = Pinecone(api_key='YOUR_API_KEY')  # or set PINECONE_API_KEY env var\n\n# Create serverless index\nif not pc.has_index('my-index'):\n    pc.create_index(\n        name='my-index',\n        dimension=1536,\n        metric='cosine',\n        spec=ServerlessSpec(cloud='aws', region='us-east-1'),\n    )\n\nindex = pc.Index('my-index')\n\n# Upsert vectors\nindex.upsert(vectors=[\n    {'id': 'v1', 'values': [0.1] * 1536, 'metadata': {'source': 'doc1'}},\n])\n\n# Query\nresults = index.query(vector=[0.1] * 1536, top_k=5, include_metadata=True)\nprint(results)","lang":"python","description":"v3+ uses object-oriented client. ServerlessSpec replaces the old environment string. Pod indexes use PodSpec instead."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"< 3.0"},{"fix":"pip uninstall pinecone-client followed by pip install pinecone. Order matters — do not install both simultaneously.","message":"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.","severity":"breaking","affected_versions":"< 5.1.0"},{"fix":"Upgrade to Python 3.10+.","message":"Python 3.9 dropped in v8.0.0 (released Nov 2025). Python 3.9 reached EOL Oct 2, 2025.","severity":"breaking","affected_versions":">= 8.0.0"},{"fix":"Use the default REST client (pip install pinecone) unless gRPC is specifically needed. Isolate in a virtual environment if grpcio version conflicts occur.","message":"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.","severity":"breaking","affected_versions":">= 4.0.0"},{"fix":"Check index type before applying configuration. Use pc.describe_index('name').spec to inspect whether the index is serverless or pod-based.","message":"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.","severity":"gotcha","affected_versions":">= 3.0.0"},{"fix":"Poll pc.describe_index('name').status.ready or use pc.create_index(..., timeout=-1) to block until ready before proceeding.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Flatten metadata before upserting. Convert nested structures to strings or top-level keys. Validate metadata types before upsert calls.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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).","severity":"breaking","affected_versions":"all (for pinecone[grpc])"}],"env_vars":null,"last_verified":"2026-05-12T06:18:11.419Z","next_check":"2026-05-28T00:00:00.000Z","problems":[{"fix":"Install the Pinecone package using pip: 'pip install pinecone'.","cause":"The 'pinecone' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'pinecone'"},{"fix":"Upgrade the Pinecone SDK to the latest version: 'pip install pinecone --upgrade'.","cause":"Using an outdated version of the Pinecone SDK where the 'Pinecone' class is not available.","error":"ImportError: cannot import name 'Pinecone' from 'pinecone'"},{"fix":"Use the 'Pinecone' class for initialization: 'from pinecone import Pinecone; pc = Pinecone(api_key=api_key)'.","cause":"Attempting to use the 'init' method, which is not present in newer versions of the Pinecone SDK.","error":"AttributeError: module 'pinecone' has no attribute 'init'"},{"fix":"Use the 'Pinecone' class for client initialization: 'from pinecone import Pinecone; pc = Pinecone(api_key=api_key)'.","cause":"The 'Client' class has been removed or renamed in newer versions of the Pinecone SDK.","error":"ImportError: cannot import name 'Client' from 'pinecone'"},{"fix":"Ensure you have the latest version of the Pinecone SDK installed: 'pip install pinecone --upgrade'.","cause":"The 'GRPCIndex' class has been removed or is not available in the current version of the Pinecone SDK.","error":"ImportError: cannot import name 'GRPCIndex' from 'pinecone'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":5.5,"disk_size":"34.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"grpc","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":5.5,"disk_size":"34.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":5.5,"disk_size":"33.2M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":5.5,"disk_size":"35M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"grpc","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":5.5,"disk_size":"35M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":5.5,"disk_size":"34M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.44,"mem_mb":6.7,"disk_size":"37.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"grpc","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":6.7,"disk_size":"37.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":6.7,"disk_size":"36.5M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.33,"mem_mb":6.7,"disk_size":"38M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"grpc","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.33,"mem_mb":6.7,"disk_size":"38M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.35,"mem_mb":6.7,"disk_size":"37M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":8.5,"disk_size":"28.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"grpc","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.4,"mem_mb":8.5,"disk_size":"28.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.45,"mem_mb":8.5,"disk_size":"27.9M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":8.5,"disk_size":"29M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"grpc","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.45,"mem_mb":8.5,"disk_size":"29M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":8.5,"disk_size":"28M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":12.4,"disk_size":"36.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"grpc","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":12.4,"disk_size":"27.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":12.4,"disk_size":"39M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"grpc","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.48,"mem_mb":12.4,"disk_size":"55M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.48,"mem_mb":12.4,"disk_size":"28M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":8.4,"disk_size":"40.2M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"grpc","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":8.4,"disk_size":"31.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"asyncio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.29,"mem_mb":8.4,"disk_size":"43M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"grpc","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":8.4,"disk_size":"58M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":8.4,"disk_size":"31M"}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}