pydantic BaseSettings has been moved to pydantic-settings (tested)

PydanticImportError: `BaseSettings` has been moved to the `pydantic-settings` package appears when code written for Pydantic 1 runs on Pydantic 2. Fix: pip install pydantic-settings and import BaseSettings from pydantic_settings.

1. The error, and two v1 imports that only warn

for stmt in ["from pydantic import BaseSettings",
             "from pydantic.error_wrappers import ValidationError",
             "from pydantic import validator"]:
    try:
        exec(stmt)
        print(f"{stmt}: ok")
    except Exception as e:
        print(f"{stmt}:\n  {type(e).__name__}: {e}")

Output:

from pydantic import BaseSettings:
  PydanticImportError: `BaseSettings` has been moved to the `pydantic-settings` package. See https://pydantic.dev/docs/validation/2.14/migration/#basesettings-has-moved-to-pydantic-settings for more details.

For further information visit https://errors.pydantic.dev/2.14/u/import-error
<string>:1: PydanticDeprecatedSince20: `pydantic.error_wrappers:ValidationError` has been moved to `pydantic:ValidationError`. Deprecated in Pydantic V2.0 to be removed in V3.0. See Pydantic V2 Migration Guide at https://errors.pydantic.dev/2.14/migration/
from pydantic.error_wrappers import ValidationError: ok
from pydantic import validator: ok

In Pydantic 2 the settings class lives in a separate package, so from pydantic import BaseSettings fails with PydanticImportError. Other v1 imports are softer: pydantic.error_wrappers.ValidationError still imports with a PydanticDeprecatedSince20 warning, and validator still imports (it is deprecated in favour of field_validator).

2. Fix: install pydantic-settings

pip install pydantic-settings

import os
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="APP_")
    database_url: str = "sqlite:///dev.db"
    debug: bool = False
os.environ["APP_DEBUG"] = "true"
print(Settings())
from pydantic import ValidationError    # v2: import it from pydantic directly
print(ValidationError.__module__)

Output:

database_url='sqlite:///dev.db' debug=True
pydantic_core._pydantic_core

Change the import to from pydantic_settings import BaseSettings. The v1 inner class Config: env_prefix = ... becomes model_config = SettingsConfigDict(env_prefix=...). Environment variables are still read and converted (APP_DEBUG=true became debug=True). Add pydantic-settings to your requirements file too, or the error comes back in CI or Docker.

3. Code that must run on v1 and v2, or a quick stopgap

import warnings; warnings.simplefilter("always")
from pydantic.errors import PydanticImportError
print("PydanticImportError is an ImportError:", issubclass(PydanticImportError, ImportError))
try:
    from pydantic import BaseSettings
except ImportError:                      # works for code that must run on v1 and v2
    from pydantic_settings import BaseSettings
print("got", BaseSettings.__module__)
try:
    from pydantic.v1 import BaseSettings as V1Settings
    print("pydantic.v1 BaseSettings:", V1Settings.__module__)
except Exception as e:
    print(f"pydantic.v1: {type(e).__name__}: {e}")

Output:

PydanticImportError is an ImportError: True
got pydantic_settings.main
pydantic.v1 BaseSettings: pydantic.v1.env_settings

PydanticImportError is a subclass of ImportError, so a try/except ImportError fallback works for libraries that support both major versions. pydantic.v1 still ships the old BaseSettings in 2.14.1 as a stopgap, but it is the v1 API (models built with it are v1 models); migrate rather than staying on it.

Related: FastAPI 422 Unprocessable Entity (Pydantic validation errors in FastAPI).

Written with AI assistance. Measured on 2026-10-23 with Pydantic 2.14.1, pydantic-settings 2.16.1 and Python 3.14.7 (python:3-alpine in Docker). Each block was run verbatim and the output pasted unedited. PlainHeaders is our extension; Python and Pydantic are free.