ErrLookup › Background articles › "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed

"X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed

"The X package is not installed. Please install it with pip install X" — this error family covers ImportError, ValueError, and RuntimeError messages raised when a library lazily imports an optional dependency (an extra, a separate distribution, or a vendor-only package) that is not present in the running environment. Developers meet it at first use of a feature — enabling a callback, constructing an embedding function, saving a file, or logging in — on slim Docker images, fresh venvs, pruned npm installs, or machines where the base package was installed without its extras.

Distilled from 119 documented records across 22 repositories.

Background

Libraries keep their install footprint small by declaring heavyweight or niche integrations as optional dependencies: pip extras (litellm[grpc], yt-dlp[default]), optionalDependencies in package.json, or separate distributions entirely (litellm-enterprise, sgl-kernel). The code that needs such a dependency typically wraps its import in a try block or a soft-import guard at module load, caches the failure, and later re-raises it as a friendlier error — ImportError chained via 'raise ... from exc', or converted to ValueError/RuntimeError — with an explicit install instruction. That is why the message reads like the opening of record [5]: "The boto3 python package is not installed. Please install it with `pip install boto3`".

From the caller's side the failure almost never happens at import time of the host library; it fires lazily at the moment the feature is exercised. LiteLLM raises OTel exporter errors while building span/metric/log providers at startup ([3], [4], [9], [10], [14], [19]), but its NVIDIA Riva error only appears on the first transcription call ([24]). Chroma raises ValueError in an embedding function's constructor, before any embedding is computed ([5], [11], [16], [18], [29]). Angular's ServerXhr is a variant: the failure is a race/state error ('XHR implementation is not loaded') caused by a lazy dynamic import of xhr2 that never completed ([6]), and npm-ecosystem libraries see the same family when optionalDependencies are pruned at install time, as with GitNexus's onnxruntime-node whose postinstall could not download CUDA binaries ([1]).

The family also includes genuinely unavailable dependencies, not merely uninstalled ones. LiteLLM's 'enterprise folder' callbacks ([2], [15]) can never be satisfied by pip because the enterprise package ships only inside the official Docker image, and the litellm-enterprise callbacks ([0], [7], [28]) additionally gate on a license after the import succeeds. Some members are conditional capability checks rather than missing packages: matplotlib raises 'cairo has not compiled with SVG support' when the installed native cairo lacks a surface ([26]), nautilus_trader demands pandas only when a nanosecond remainder would lose precision ([21]), and yt-dlp's ivi.ru extractor reports the missing crypto module only after the signed request path it would have enabled was skipped ([20]). A few libraries attempt auto-install — ruflo's AIDefence loader tries once per process and permanently short-circuits after a failed attempt, requiring a restart ([12]).

Common causes

Base install without extras. Installing the library bare (pip install litellm, pip install chromadb, bare yt-dlp) omits optional extras like opentelemetry-exporter-otlp, grpcio, boto3, fastembed, pillow, nomic, openai, or pycryptodomex. The error appears the first time the corresponding feature is used.
Slim or pruned container images. Docker images built from minimal lockfiles or aggressive dependency pruning drop heavy optional packages — grpcio on alpine/slim bases, OTel exporters, or provider SDKs. LiteLLM's OTel errors are most common on slim images and lockfiles predating the OTel adoption ([3], [9], [10]).
Config/requirements drift. Configuration enables a feature whose dependency was never added to the deployment: callbacks like 'hide_secrets' or 'llamaguard_moderations' in config.yaml without litellm-enterprise in requirements, or OTEL_EXPORTER=otlp_grpc without litellm[grpc]. The failure occurs at config load in the deploy environment but not on the dev machine where it was tested.
Dependency that cannot be installed via pip at all. Some packages are structurally unavailable: LiteLLM's 'enterprise' folder exists only in the official Docker image, so a pip-installed proxy can never load openai_moderations or google_text_moderation ([2], [15]); panopticapi must be installed from git ([23]); the vendored FA4 CUTE interface requires a matching sgl-kernel build and CUDA platform ([22]).
Version drift or broken install. The package is present but imports incompletely — an a2a-sdk that installs but lacks the compat module litellm expects ([13], [25]), a numpy-incompatible panopticapi ([23]), or a corrupted venv — leaving cached soft-import guards in a failed state.
Postinstall/network failures pruning optional packages. In the npm world, optionalDependencies are silently dropped when their postinstall fails: onnxruntime-node's CUDA download from api.nuget.org fails behind proxies and firewalls, so @huggingface/transformers is pruned and the dynamic import later fails ([1]).
Failed auto-install cached per process. Loaders that auto-install optional packages remember the failure: ruflo's AIDefence flag allows at most one install attempt per process, so every later call throws until the package is manually installed and the server restarted ([12]).
Missing native capability in a present dependency. The dependency exists but lacks the needed feature: a libcairo build compiled without SVG support has no SVGSurface attribute and matplotlib refuses to create it ([26]); nautilus_trader requires pandas only when a nanosecond remainder would silently lose precision ([21]).

What usually fixes it

Install the named dependency in the exact environment that runs the code — the deployed image or venv, not a local shell — then restart the process so cached import guards and per-process flags reset; verify with the import command the error or documentation suggests (e.g. python -c "from X import Y").
Prefer the library's bundled extra over ad hoc installs (litellm[grpc], litellm[extra_proxy], yt-dlp[default]) so transitive requirements and version constraints are pinned together; prefer official release binaries or Docker images that bundle optional deps when available.
Switch to an alternate feature path that needs no extra dependency: OTEL_EXPORTER=console or otlp_http instead of gRPC, cookies-based login instead of password login, the fetch HttpClient backend instead of XHR, or microsecond-aligned timestamps instead of ns precision.
Ship the dependency and the config that needs it in the same change (requirements + config in one PR), and add build-time or healthcheck import probes for every optional integration enabled, so failures surface at deploy time rather than first use.
When the dependency cannot exist in your install type (Docker-only enterprise folders, git-only packages), change the deployment model — run the official image or vendor the package — or remove the feature from the config; remember some gates are followed by a license check even after the import succeeds.

Go deeper

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Documented occurrences

…and 99 more across the corpus — use search.

Honest provenance: generated on 2026-08-28 from AI-assisted analysis of the linked records. See how records are made.