{"record":{"id":"ef6c459a0cbb996f","repo":"BoundaryML/baml","slug":"msg-please-upgrade-baml-py-to-the-latest-version-pip-install","errorCode":null,"errorMessage":"{msg}\n\nPlease upgrade baml-py to the latest version.\n\n$ pip install {self._target_package_name()}\n$ uv add {self._target_package_name()}\n\nIf nothing else works, please ask for help:\n\nhttps://github.com/boundaryml/baml/issues\nhttps://boundaryml.com/discord","messagePattern":"(.+?)\n\nPlease upgrade baml-py to the latest version\\.\n\n\\$ pip install (.+?)\n\\$ uv add (.+?)\n\nIf nothing else works, please ask for help:\n\nhttps://github\\.com/boundaryml/baml/issues\nhttps://boundaryml\\.com/discord","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"engine/language_client_python/python_src/baml_py/safe_import.py","lineNumber":51,"sourceCode":"\n    def _target_package_name(self) -> str:\n        if __target_baml_py_version__ is None:\n            return \"-U baml-py\"\n        return f\"baml-py=={__target_baml_py_version__}\"\n\n    def raise_if_incompatible_version(self, current_version: str):\n        if not self._is_version_compatible(current_version, __baml_py_version__):\n            self.raise_version_error(f\"\"\"\nbaml-py is likely out of date.\n                                     \nVersion of baml_client generator (see generators.baml): {current_version}\nCurrent version of baml-py: {__baml_py_version__}\n\"\"\".strip())\n\n    def raise_version_error(self, msg: str):\n        target_version = __target_baml_py_version__\n        if target_version is None:\n            raise ImportError(f\"\"\"\n{msg}\n\nPlease upgrade baml-py to the latest version.\n\n$ pip install {self._target_package_name()}\n$ uv add {self._target_package_name()}\n\nIf nothing else works, please ask for help:\n\nhttps://github.com/boundaryml/baml/issues\nhttps://boundaryml.com/discord\n\n\"\"\".strip()) from None\n        else:\n            raise ImportError(f\"\"\"\n{msg}\n\nPlease set baml-py to version \"{target_version}\".","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_python/python_src/baml_py/safe_import.py#L33-L69","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\n$ baml-cli generate   # CLI v0.80.0\n# baml-py==0.74.0 installed -> ImportError\n\n# after\n$ pip install -U baml-py\n$ baml-cli generate  # versions aligned","handlingStrategy":"try-catch","validationCode":"import importlib.metadata\nv = importlib.metadata.version(\"baml-py\")\nassert v is not None and len(v.split(\".\")) >= 2, \"baml-py not installed or malformed version\"","typeGuard":"def baml_py_installed() -> bool:\n    try:\n        importlib.metadata.version(\"baml-py\")\n        return True\n    except importlib.metadata.PackageNotFoundError:\n        return False","tryCatchPattern":"try:\n    import baml_py\nexcept ImportError as e:\n    if \"Please upgrade baml-py\" in str(e):\n        subprocess.run([\"pip\", \"install\", \"-U\", \"baml-py\"], check=True)\n    raise","preventionTips":["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"],"tags":["python","version-mismatch","import","dependency"],"backgroundTag":"dependency-version-incompatible","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}