BoundaryML/baml · error · ImportError

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

Error message

{msg}

Please set baml-py to version "{target_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 baml-py's version is incompatible and a specific target version IS known (__target_baml_py_version__ is set by the generated client). The message instructs you to install exactly that pinned baml-py version. This keeps the generated Python client in lockstep with the native engine it was generated against.

Source

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

    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}".

$ 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
        

    def __exit__(self, exc_type: Optional[Type[Exception]], exc_value: Optional[Exception], traceback):
        if exc_type is not None:
            if isinstance(exc_value, ImportError) and "baml_py" in str(exc_value):
                self.raise_version_error(exc_value.args[0])

View on GitHub (pinned to bd85ce9dee)

Solutions

Install the exact version named in the message: `pip install baml-py==<target_version>` (or `uv add baml-py==<target_version>`).
Update requirements.txt/pyproject/lockfile to pin baml-py to that target version.
Alternatively, upgrade the BAML CLI and regenerate so the target version matches your environment.
Recreate your virtualenv to flush stale baml-py installs if pip resolution keeps the old wheel.

Example fix

# before (requirements.txt)
baml-py==0.74.0   # client generated for 0.82.0 -> ImportError

# after (requirements.txt)
baml-py==0.82.0

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.metadata
installed = importlib.metadata.version("baml-py")
# target version is stated in the ImportError message; keep it in requirements.txt
assert installed in ALLOWED_BAML_PY_VERSIONS, f"baml-py=={installed} not the pinned target"

Type guard

def is_pinned_baml_py(target: str) -> bool:
    try:
        return importlib.metadata.version("baml-py") == target
    except importlib.metadata.PackageNotFoundError:
        return False

Try / catch

try:
    import baml
except ImportError as e:
    m = re.search(r'set baml-py to version "([^"]+)"', str(e))
    if m:
        subprocess.run(["pip", "install", f"baml-py=={m.group(1)}"], check=True)
    raise

Prevention

Always pin the exact baml-py version named by the generated client
Commit regenerated clients and updated pins in the same PR
Use a lockfile (pip-tools/uv lock) so CI installs the exact version
Recreate the virtualenv after changing BAML versions to flush stale wheels

When it happens

Trigger: Importing baml_py when the installed baml-py version differs from the version baked into the generated client code, which raises via raise_version_error with the exact required pin.

Common situations: A teammate regenerated clients with a newer BAML CLI but requirements.txt still pins the old baml-py; CI installs a cached baml-py wheel of a different version; switching branches where the generated client's target version changed.

Related errors

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