{"record":{"id":"75dcf4b6f4b97879","repo":"BoundaryML/baml","slug":"msg-please-set-baml-py-to-version-target-version-pip-install","errorCode":null,"errorMessage":"{msg}\n\nPlease set baml-py to version \"{target_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 set baml-py to 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":66,"sourceCode":"    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}\".\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\"\"\".strip()) from None\n        \n\n    def __exit__(self, exc_type: Optional[Type[Exception]], exc_value: Optional[Exception], traceback):\n        if exc_type is not None:\n            if isinstance(exc_value, ImportError) and \"baml_py\" in str(exc_value):\n                self.raise_version_error(exc_value.args[0])","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_python/python_src/baml_py/safe_import.py#L48-L84","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before (requirements.txt)\nbaml-py==0.74.0   # client generated for 0.82.0 -> ImportError\n\n# after (requirements.txt)\nbaml-py==0.82.0","handlingStrategy":"try-catch","validationCode":"import importlib.metadata\ninstalled = importlib.metadata.version(\"baml-py\")\n# target version is stated in the ImportError message; keep it in requirements.txt\nassert installed in ALLOWED_BAML_PY_VERSIONS, f\"baml-py=={installed} not the pinned target\"","typeGuard":"def is_pinned_baml_py(target: str) -> bool:\n    try:\n        return importlib.metadata.version(\"baml-py\") == target\n    except importlib.metadata.PackageNotFoundError:\n        return False","tryCatchPattern":"try:\n    import baml\nexcept ImportError as e:\n    m = re.search(r'set baml-py to version \"([^\"]+)\"', str(e))\n    if m:\n        subprocess.run([\"pip\", \"install\", f\"baml-py=={m.group(1)}\"], check=True)\n    raise","preventionTips":["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"],"tags":["python","version-mismatch","import","dependency","pinning"],"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"}