pydantic "ImportError: cannot import name 'BaseSettings'" (pydantic-settings) in CI

In pydantic v2, BaseSettings was moved out of the core package into pydantic-settings. Code that still does from pydantic import BaseSettings raises an ImportError once v2 is installed.

What this error means

Startup fails with "ImportError: cannot import name 'BaseSettings' from 'pydantic'" after pydantic resolved to v2.

ImportError: cannot import name 'BaseSettings' from 'pydantic'
(/opt/venv/lib/python3.12/site-packages/pydantic/__init__.py)

Common causes

BaseSettings moved to pydantic-settings in v2

The class is no longer exported from pydantic; it now lives in the pydantic-settings distribution.

The new package is not installed

Code imports from pydantic_settings, but the pydantic-settings dependency was never added to requirements.

How to fix it

Install pydantic-settings and update imports

1. Add pydantic-settings to requirements.
2. Import BaseSettings from pydantic_settings instead of pydantic.
3. Move SettingsConfigDict usage as needed.

# pip install pydantic-settings
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    database_url: str
    model_config = SettingsConfigDict(env_file=".env")

Or pin pydantic to v1 temporarily

If you are not ready to split the package, pin v1 where BaseSettings is still in core.

pip install "pydantic<2"

How to prevent it

• Add pydantic-settings when you move to pydantic v2.
• Pin pydantic so the move is intentional.
• Grep for from pydantic import BaseSettings before upgrading.

Related guides