BoundaryML/baml · error · ImportError

{msg} Please upgrade baml-py to the latest version. $ pip

Error message

{msg}

Please upgrade baml-py to the latest version.

$ pip install {self._target_package_name()}
$ uv add {self._target_package_name()}

If nothing else works, please ask for help:

https://github.com/boundaryml/baml/issues
https://boundaryml.com/discord

What it means

safe_import.py raises this ImportError when the installed baml-py version is incompatible with the BAML client and no pinned target version (__target_baml_py_version__) is known, so it cannot suggest an exact pin. It tells you to upgrade baml-py to the latest release. This guards against ABI/API drift between generated client code and the native baml-py wheel.

Source

Thrown at engine/language_client_python/python_src/baml_py/safe_import.py:51

    def _target_package_name(self) -> str:
        if __target_baml_py_version__ is None:
            return "-U baml-py"
        return f"baml-py=={__target_baml_py_version__}"

    def raise_if_incompatible_version(self, current_version: str):
        if not self._is_version_compatible(current_version, __baml_py_version__):
            self.raise_version_error(f"""
baml-py is likely out of date.
                                     
Version of baml_client generator (see generators.baml): {current_version}
Current version of baml-py: {__baml_py_version__}
""".strip())

    def raise_version_error(self, msg: str):
        target_version = __target_baml_py_version__
        if target_version is None:
            raise ImportError(f"""
{msg}

Please upgrade baml-py to the latest version.

$ pip install {self._target_package_name()}
$ uv add {self._target_package_name()}

If nothing else works, please ask for help:

https://github.com/boundaryml/baml/issues
https://boundaryml.com/discord

""".strip()) from None
        else:
            raise ImportError(f"""
{msg}

Please set baml-py to version "{target_version}".

View on GitHub (pinned to bd85ce9dee)

Solutions

Run `pip install -U baml-py` (or `uv add baml-py`) to get the latest version matching your CLI.
Regenerate the client with the same BAML CLI version you use at runtime (`baml-cli generate`).
Pin baml-py and the @boundaryml/baml CLI/extension to the same version in your lockfile/requirements.
If versions appear aligned but the error persists, report at github.com/boundaryml/baml or the Discord.

Example fix

# before
$ baml-cli generate   # CLI v0.80.0
# baml-py==0.74.0 installed -> ImportError

# after
$ pip install -U baml-py
$ baml-cli generate  # versions aligned

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.metadata
v = importlib.metadata.version("baml-py")
assert v is not None and len(v.split(".")) >= 2, "baml-py not installed or malformed version"

Type guard

def baml_py_installed() -> bool:
    try:
        importlib.metadata.version("baml-py")
        return True
    except importlib.metadata.PackageNotFoundError:
        return False

Try / catch

try:
    import baml_py
except ImportError as e:
    if "Please upgrade baml-py" in str(e):
        subprocess.run(["pip", "install", "-U", "baml-py"], check=True)
    raise

Prevention

Pin baml-py and the BAML CLI to the same version in lockfiles
Run `pip install -U baml-py` whenever you upgrade the BAML CLI/extension
Regenerate clients and upgrade the wheel together in CI
Rebuild the virtualenv when switching BAML versions

When it happens

Trigger: Importing baml (or calling raise_if_incompatible_version / __exit__) when the version check fails and __target_baml_py_version__ is None — typically with a generated client from a different BAML CLI version than the installed baml-py wheel.

Common situations: Upgrading the BAML CLI (or VS Code extension) and regenerating clients without `pip install -U baml-py`; committing a lockfile that pins an old baml-py while teammates use a newer CLI; mixing baml-py from PyPI with a dev build of the engine.

Related errors

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/ef6c459a0cbb996f. Report an issue: GitHub.