Learn AI Create the Future — with Pranay
Main site

Error database

PydanticImportError: BaseSettings has been moved to the pydantic-settings package

Pydantic v2 moved BaseSettings into its own package. Install pydantic-settings and update the import — or upgrade the old library that still imports it from pydantic.

The message you saw
PydanticImportError: BaseSettings has been moved to the pydantic-settings package

By Updated

The error

Output
pydantic.errors.PydanticImportError: `BaseSettings` has been moved to the `pydantic-settings` package. See https://docs.pydantic.dev/2.11/migration/#basesettings-has-moved-to-pydantic-settings for more details.

What it means

Pydantic is the validation library underneath much of the AI tooling stack — FastAPI, LangChain, the OpenAI and Anthropic SDKs all build on it. Pydantic v2 (mid-2023) was a rewrite, and BaseSettings — the class for loading configuration from environment variables — moved out of the core into a companion package, pydantic-settings. Code importing it from pydantic fails on any v2 install.

Why it happens

Either your own code carries the v1-style import, usually copied from an older FastAPI or LangChain tutorial, or a dependency does. Since half the ecosystem depends on pydantic, one pip install of something modern silently upgrades pydantic to v2 and breaks the old import elsewhere. The traceback's file path tells you whose import it is.

How to fix it

1. For your own code: install the package, change the import.

bash
pip install pydantic-settings
python
from pydantic_settings import BaseSettings      # was: from pydantic import BaseSettings

class Settings(BaseSettings):
    openai_api_key: str
    model_name: str = "gpt-4o-mini"

settings = Settings()                            # reads environment variables

For most settings classes this is the entire migration.

2. If the traceback points into a dependency, upgrade that dependency. Maintained libraries shipped pydantic-v2-compatible releases long ago:

bash
pip install -U theoldlibrary

3. Pinning pydantic<2 is the last resort, and increasingly expensive. Modern FastAPI, LangChain and the LLM SDKs expect v2; the pin will collide with them sooner rather than later. Use it only to keep an unmaintained system alive, isolated in its own environment.

4. Watch for the sibling v2 breaks while migrating. .dict() became .model_dump(), .parse_obj() became .model_validate(), and @validator became @field_validator. Fixing the BaseSettings import often reveals these next.

How to prevent it

Treat pydantic as infrastructure: know which major version your project targets, pin it (pydantic>=2,<3), and check dependencies' pydantic requirements before adding them. When following tutorials, anything importing BaseSettings from bare pydantic predates v2 and needs the one-line translation.