Pydantic v2 "BaseSettings has been moved" in CI

By Daniel Zoghalchali·Latchkey

Pydantic v2 removed BaseSettings from the core package and relocated it to the separate pydantic-settings distribution. Code that still imports it from pydantic raises on import after the upgrade.

What this error means

After a pydantic 2.x upgrade, importing settings fails with "PydanticImportError: BaseSettings has been moved to the pydantic-settings package."

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

Diagnose it: which interpreter and which environment?

which -a python python3 pip
python -c "import sys; print(sys.executable); print(sys.version)"
python -c "import sys; [print(p) for p in sys.path]"
pip list 2>/dev/null | head -20

Common causes

BaseSettings imported from pydantic on v2

In v2 the class lives in pydantic_settings, not pydantic, so the old import path no longer resolves.

pydantic-settings is not installed

Even with the corrected import, the new dependency must be added to the environment.

How to fix it

Install pydantic-settings and fix the import

1. Add pydantic-settings to your dependencies.
2. Import BaseSettings from pydantic_settings.
3. Replace class Config with model_config = SettingsConfigDict(...) per v2.

from pydantic_settings import BaseSettings, SettingsConfigDict

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

Pin pydantic v1 to defer the migration

If you cannot migrate now, cap pydantic below 2 so the old import keeps working.

pip install "pydantic<2"

How to prevent it

• Track the pydantic v2 migration guide when bumping the major version.
• Add pydantic-settings whenever you use BaseSettings on v2.
• Pin pydantic in a lockfile so major bumps are intentional.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation