Registry /
vector-search / llama-index-vector-stores-pinecone
Install & Compatibility
Where this runs
tested against v0.8.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 4.950s · 263.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 20.8s · import 4.560s · 260MB
291MB installed
● package 291MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PineconeVectorStore
✓ from llama_index.vector_stores.pinecone import PineconeVectorStore
VectorStoreIndex
✓ from llama_index.core import VectorStoreIndex
SimpleDirectoryReader
✓ from llama_index.core import SimpleDirectoryReader
StorageContext
✓ from llama_index.core import StorageContext
Pinecone
✓ from pinecone import Pinecone
✗ from llama_index.vector_stores.pinecone import Pinecone
The Pinecone client itself is imported directly from the `pinecone` package, not from the LlamaIndex integration.
This quickstart demonstrates how to set up a Pinecone index, initialize `PineconeVectorStore`, load documents using `SimpleDirectoryReader`, and build a `VectorStoreIndex` for querying. It assumes `PINECONE_API_KEY` and `OPENAI_API_KEY` are set as environment variables.
import os
from pinecone import Pinecone, ServerlessSpec
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, StorageContext
from llama_index.vector_stores.pinecone import PineconeVectorStore
# Set your API keys (replace with actual keys or use environment variables)
os.environ['PINECONE_API_KEY'] = os.environ.get('PINECONE_API_KEY', 'YOUR_PINECONE_API_KEY')
os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY')
# Initialize Pinecone
pc = Pinecone(api_key=os.environ['PINECONE_API_KEY'])
index_name = "quickstart-index"
if index_name not in pc.list_indexes().names():
pc.create_index(
name=index_name,
dimension=1536, # Dimension for OpenAI's text-embedding-ada-002
metric="cosine",
spec=ServerlessSpec(cloud="aws", region="us-west-2")
)
pinecone_index = pc.Index(index_name)
# Initialize PineconeVectorStore
vector_store = PineconeVectorStore(pinecone_index=pinecone_index)
# Load documents (create a 'data' directory with text files or adjust path)
try:
documents = SimpleDirectoryReader(input_dir="./data").load_data()
except FileNotFoundError:
print("Please create a 'data' directory and add some text files, or modify SimpleDirectoryReader path.")
documents = []
if documents:
# Set up StorageContext
storage_context = StorageContext.from_defaults(vector_store=vector_store)
# Create VectorStoreIndex
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)
# Query the index
query_engine = index.as_query_engine()
response = query_engine.query("What is this document about?")
print(response.response)
else:
print("No documents loaded. Skipping index creation and query.")
Debug
Known issues
breakingLlamaIndex v0.10.0 introduced a major packaging refactor. Core components moved to `llama-index-core`, and integrations like `pinecone-vector-store` are now separate PyPI packages.fixEnsure you `pip install llama-index-core` and `pip install llama-index-vector-stores-pinecone`. Update imports from `from llama_index import ...` to `from llama_index.core import ...` for core components and `from llama_index.vector_stores.pinecone import ...` for this integration. The `ServiceContext` abstraction has also been deprecated; configure LLMs/embeddings directly or use global settings.
affects: >=0.10.0 of `llama-index` core (and `llama-index-vector-stores-pinecone` versions compatible with it)
gotchaPinecone index dimensions must match the embedding model's output dimension. Mismatched dimensions will lead to errors during upsert operations.fixWhen creating a Pinecone index (e.g., `pc.create_index`), ensure the `dimension` parameter matches the output dimension of your chosen embedding model (e.g., 1536 for OpenAI's `text-embedding-ada-002`). Refer to your embedding model's documentation for the correct dimension.
affects: All
gotchaInconsistent or empty query results from Pinecone often stem from issues with API keys, index state, overly restrictive filters, or problems during document ingestion.fixVerify `PINECONE_API_KEY` is correct and has access to the specified index. Check if documents were successfully added to Pinecone. Review any `MetadataFilters` applied during querying to ensure they are not inadvertently excluding relevant results. For persistent issues, inspect Pinecone's dashboard to confirm index content and health.
affects: All
gotchaCompatibility issues can arise when `pinecone-client` is installed alongside other libraries that also depend on it (e.g., `langchain-pinecone`), leading to version downgrades or conflicts.fixUse `pip install --upgrade` for specific packages to force the desired versions, or install `pinecone-client` directly with a version constraint that satisfies all dependencies (e.g., `pinecone-client>=4.0.0,<5.0.0`). Check the dependency requirements of all involved libraries.
affects: All
Errors
Common errors & fixes
AttributeError: 'PineconeVectorStore' object has no attribute 'service_context'
`ServiceContext` was deprecated in LlamaIndex v0.10.0 and `PineconeVectorStore` no longer relies on it directly.
fixRemove any explicit usage of `service_context` when initializing `PineconeVectorStore` or `VectorStoreIndex`. Configure LLM and embedding models directly using `Settings` or by passing them as arguments to `VectorStoreIndex.from_documents()`.
pinecone.exceptions.PineconeException: The dimension of the vectors to be upserted (X) does not match the dimension of the index (Y).
The vector dimension generated by your embedding model does not match the dimension specified when creating the Pinecone index.
fixEnsure the `dimension` parameter in `pc.create_index()` matches the output dimension of your embedding model. For example, if using OpenAI's `text-embedding-ada-002`, the dimension should be 1536.
Index 'your-index-name' is not ready. Please wait a few seconds and try again.
The Pinecone index creation can take a short amount of time to become active and ready for operations.
fixImplement a retry mechanism with a short delay (e.g., `time.sleep(5)`) or check `pc.describe_index(index_name).status` before proceeding with upserts or queries.
Upgrade
Version history
0.8.0latest on PyPI · released Mar 12, 2026
Audit
Dependencies
llama-index-corerequiredCore LlamaIndex functionalities like VectorStoreIndex and StorageContext.
pinecone-clientrequiredOfficial Python client for interacting with Pinecone.
llama-index-embeddings-openaioptionalCommonly used embedding model for LlamaIndex applications.
openaioptionalOften used for generating embeddings when working with OpenAI's models.