Code Beginner easy · 3 min

ImportError for integration packages

What you will learn

LlamaIndex integration packages like Pinecone and Cohere must be installed separately; importing them without installation causes ImportError.

Why this matters

Developers often install llama-index-core and assume all integrations are included, then hit confusing ImportErrors in production. Understanding the modular design prevents debugging time and deployment failures.

Skip if: You don't need separate installs if you only use built-in components like SimpleDirectoryReader, Settings, or in-memory VectorStore. You only hit this when using external services (Pinecone, Weaviate, OpenAI embeddings, Cohere LLMs, etc.).

Explanation

What it is: LlamaIndex follows a modular architecture where the core package (llama-index-core) provides the framework, but connectors to external services are in separate packages like llama-index-pinecone, llama-index-cohere, llama-index-weaviate. The core package does not bundle these integrations.

How it works mechanically: When you write from llama_index.integrations.vector_stores import PineconeVectorStore, Python looks for the module in installed packages. If llama-index-pinecone is not installed, the import fails with ModuleNotFoundError. Each integration is a separate pip package that must be explicitly installed.

When to use this knowledge: Every time you use an external service (vector database, LLM provider, embedding model), verify the integration package is installed. Check the LlamaIndex integrations docs for the exact package name.

Analogy

It's like buying a car (llama-index-core) and then separately ordering wheels (llama-index-pinecone), a stereo system (llama-index-cohere), and headlights (llama-index-openai). The car frame comes pre-built, but you must order the specific parts you need.

Code

Illustrative only - not runnable without a valid API key

python

import subprocess
import sys

try:
    from llama_index.integrations.vector_stores import PineconeVectorStore
    print("Pinecone integration is installed.")
except ImportError as e:
    print(f"ImportError caught: {e}")
    print("\nInstalling llama-index-pinecone...")
    subprocess.check_call(
        [sys.executable, "-m", "pip", "install", "llama-index-pinecone", "-q"]
    )
    print("Installation complete.")
    from llama_index.integrations.vector_stores import PineconeVectorStore
    print("Pinecone integration now imported successfully.")

Output

ImportError caught: cannot import name 'PineconeVectorStore' from 'llama_index.integrations.vector_stores' (/path/to/site-packages/llama_index/integrations/vector_stores/__init__.py)

Installing llama-index-pinecone...
Installation complete.
Pinecone integration now imported successfully.

What just happened?

The code attempted to import PineconeVectorStore without the package installed, caught the ImportError, installed the missing integration package via pip, then successfully imported the module on the second attempt. This demonstrates both the problem and the solution.

Common gotcha

Developers often see the ImportError and think the core llama-index package is broken or outdated, so they reinstall it. The real issue is a missing integration package. The error message usually points to the integrations module, but the fix is installing a separate pip package, not the core package.

Error recovery

ModuleNotFoundError: No module named 'llama_index.integrations.vector_stores' (or similar)

You are trying to use an integration that does not exist in your version of llama-index-core. Verify the exact import path from the official LlamaIndex docs for your version.

ImportError: cannot import name 'PineconeVectorStore' from 'llama_index.integrations.vector_stores'

The integration package is missing. Run `pip install llama-index-pinecone` (replace 'pinecone' with the integration name you need).

ImportError after installing integration package

Clear your Python cache and restart your interpreter. Run `python -m py_compile <your_file.py>` to verify syntax, then restart the notebook or script.

Experienced dev note

In production, lock integration package versions in your requirements.txt or pyproject.toml, not just the core package. A new llama-index-cohere release can break your pipeline silently if it drops support for an old Cohere API version. Example: pin as `llama-index-cohere==0.1.5` alongside `llama-index-core==0.12.0`. Also, use Docker to freeze the entire dependency tree: this is the most reliable way to avoid 'works on my machine' integration issues.

Check your understanding

You have a script that works locally but fails in a GitHub Actions CI pipeline with 'ImportError: cannot import name PineconeVectorStore'. Your local requirements.txt has only `llama-index-core==0.12.0`. What is missing, and how would you verify the fix before deploying?

Show answer hint

A correct answer recognizes that the CI environment has not installed the integration package (llama-index-pinecone). The fix is to add `llama-index-pinecone` to requirements.txt. Verification: run `pip list` in CI and confirm both core and pinecone packages are present, or test the import in CI before deploying.

VERSION This modular design has been consistent in llama-index-core >= 0.9.0. If you are using older versions (< 0.9.0), integrations were bundled differently; upgrade to 0.12.x (April 2026) for the current stable pattern.

Once imports work, learn how to initialize these integrations with Settings: like configuring an embedding model or LLM at the application level instead of per-index.

Community Notes

No notes yetBe the first to share a version-specific fix or tip.