# Why Your langchain pip installation failed and How to Fix Import Errors

> Troubleshoot common langchain pip installation failures and resolve import errors. Fix ModuleNotFoundError by checking environments and outdated packages.

- Repository: [LangChain/langchain](https://github.com/langchain-ai/langchain)
- Tags: how-to-guide
- Published: 2026-02-14

---

**The most common reason a langchain pip installation failed is that the `langchain` namespace package is outdated, installed in the wrong Python environment, or missing required extras, causing `ModuleNotFoundError` when attempting `import langchain`.**

When you run `pip install langchain` from the **langchain-ai/langchain** monorepo, you are installing a *namespace package* that re-exports the public API from the actively maintained `langchain_v1` library. If your **langchain pip installation failed** to import despite appearing successful, the issue typically stems from environment mismatches, stale pip caches, or missing optional dependencies rather than a corrupted upstream package.

## Understanding the langchain namespace package architecture

The `langchain` distribution on PyPI is not a standalone implementation. Instead, as defined in [`libs/langchain_v1/pyproject.toml`](https://github.com/langchain-ai/langchain/blob/main/libs/langchain_v1/pyproject.toml), it acts as a thin wrapper that imports and re-exports symbols from the `langchain_v1` package located in the `libs/langchain_v1/` directory of the repository. The actual entry point resides in [`libs/langchain_v1/__init__.py`](https://github.com/langchain-ai/langchain/blob/main/libs/langchain_v1/__init__.py), which exposes the public API used when you write `import langchain`.

This architecture means that a successful `pip install` command must correctly resolve both the namespace package and its underlying `langchain_v1` dependency. If the installed version is out-of-date (pre-0.2.0) or the environment’s `PYTHONPATH` excludes the site-packages directory, the re-export chain breaks and Python raises `ModuleNotFoundError`.

## Common reasons your langchain pip installation failed

### Outdated cached wheels in pip cache

If you previously installed an earlier version of `langchain`, pip may reuse a cached wheel from `~/.cache/pip` that lacks the current [`__init__.py`](https://github.com/langchain-ai/langchain/blob/main/__init__.py) re-export logic. This stale cache prevents the namespace package from correctly proxying to `langchain_v1`.

### Python environment mismatches

Running `pip install langchain` with a `pip` executable linked to Python 2 or a different virtual environment than your runtime interpreter results in the package installing to a directory not on your current `sys.path`. This is the most frequent cause of "successful install but cannot import" scenarios.

### Missing optional dependencies (extras)

The base `langchain` package contains only core utilities. If you attempt to import components like `OpenAI` or `OpenAIEmbeddings` without installing the corresponding extras (e.g., `langchain[openai]` or `langchain[all]`), the import will fail even though the base package is present.

### Corrupt installation artifacts

An interrupted installation can leave an empty `langchain` directory in your site-packages without the necessary [`__init__.py`](https://github.com/langchain-ai/langchain/blob/main/__init__.py) file that performs the re-export from `langchain_v1`. This truncated directory prevents Python from recognizing the package as valid.

## Step-by-step fix for langchain import errors

Follow these steps to resolve the import error and verify your installation:

1. **Upgrade pip and force a fresh reinstall**

   Clear the cache and reinstall to bypass stale wheels and corrupt artifacts:

   ```bash
   python -m pip install --upgrade pip
   python -m pip uninstall -y langchain
   python -m pip install --no-cache-dir langchain[all]
   ```

   The `[all]` extra installs the core package plus common integrations required by most tutorials.

2. **Verify the import path and spec**

   Use `importlib` to confirm Python is loading the package from the correct location:

   ```python
   import importlib.util, sys
   spec = importlib.util.find_spec("langchain")
   print("Found at:", spec.origin)          # should point to site-packages/langchain/__init__.py

   print("Python path:", sys.path[:3])      # first entries must include site-packages

   ```

   If `spec.origin` is `None`, the package is not in your environment’s path.

3. **Check the installed version**

   Ensure you have version 0.2.0 or later, which uses the current `langchain_v1` re-export structure:

   ```python
   import langchain
   print("LangChain version:", langchain.__version__)   # >= 0.2.0 required

   ```

4. **Validate against the official installation guide**

   Cross-reference your steps with [`libs/langchain/README.md`](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/README.md) in the repository, which documents the correct pip invocation and troubleshooting steps for the monorepo structure.

## Alternative: Importing from langchain-core directly

If the top-level `langchain` namespace continues to fail, you can bypass the re-export layer entirely by installing and importing from the underlying core library:

```bash
python -m pip install langchain-core

```

Then import primitives directly from the sub-package:

```python
from langchain_core.prompts import PromptTemplate
from langchain_core.runnables import RunnableSequence

```

This method relies only on `langchain_core` and avoids the namespace package redirection defined in [`libs/langchain_v1/__init__.py`](https://github.com/langchain-ai/langchain/blob/main/libs/langchain_v1/__init__.py).

## Verification code examples

Once installed, verify functionality with these patterns from the **langchain-ai/langchain** source:

**Example 1: Basic LLM import and call**

```python
from langchain.llms import OpenAI  # pulls implementation from langchain_v1.llms.openai

llm = OpenAI(model_name="gpt-3.5-turbo")
print(llm("What is the capital of France?"))

```

**Example 2: Optional embeddings integration**

```python
from langchain.embeddings import OpenAIEmbeddings  # requires langchain[openai] extra

emb = OpenAIEmbeddings()
print(emb.embed_query("machine learning"))

```

**Example 3: Direct core usage when namespace fails**

```python
from langchain_core.prompts import PromptTemplate

template = PromptTemplate.from_template("Tell me a joke about {topic}.")
print(template.format(topic="cats"))

```

## Summary

- The `langchain` package is a **namespace package** that re-exports from `langchain_v1` via [`libs/langchain_v1/__init__.py`](https://github.com/langchain-ai/langchain/blob/main/libs/langchain_v1/__init__.py).
- **langchain pip installation failed** errors usually result from stale pip caches, environment mismatches, or missing extras—not a broken repository.
- Resolve by using `python -m pip install --no-cache-dir langchain[all]` to ensure alignment between your pip and python executables.
- Verify installation with `importlib.util.find_spec("langchain")` and check for version `>= 0.2.0`.
- As a fallback, install `langchain-core` and import directly from `langchain_core` to bypass namespace issues.

## Frequently Asked Questions

### Why does `import langchain` raise `ModuleNotFoundError` immediately after a successful pip install?

This occurs when the `pip` executable used for installation belongs to a different Python interpreter than the one running your script. Always use `python -m pip install langchain` to guarantee the package installs into the same environment that executes the import.

### How can I verify which Python environment contains my langchain installation?

Run `import importlib.util; print(importlib.util.find_spec("langchain").origin)` in your Python interpreter. The printed path should reside within your current virtual environment’s `site-packages` directory. If the result is `None`, the package is not available to that interpreter.

### What is the difference between the `langchain` and `langchain-core` packages?

`langchain-core` (located in `libs/core/` in the repository) contains the fundamental primitives like `PromptTemplate` and `Runnable` interfaces. The `langchain` package (defined in [`libs/langchain_v1/pyproject.toml`](https://github.com/langchain-ai/langchain/blob/main/libs/langchain_v1/pyproject.toml)) provides a convenience namespace that re-exports these primitives plus high-level components like LLM wrappers. You can use `langchain-core` independently if the main namespace package fails to load.

### Should I use `pip install langchain` or `pip install langchain[all]`?

Use `pip install langchain[all]` if you are following tutorials that utilize OpenAI, Anthropic, or other cloud providers, as the `[all]` extra installs the necessary dependencies for these integrations. For production deployments with specific vendors, install only the required extra (e.g., `langchain[openai]`) to minimize dependency bloat.