{"record":{"id":"fcf9c629bc472cd1","repo":"google-research/timesfm","slug":"failed-to-load-the-xreg-module-did-you-forget-to","errorCode":null,"errorMessage":"Failed to load the XReg module. Did you forget to install `timesfm[xreg]`?","messagePattern":"Failed to load the XReg module\\. Did you forget to install `timesfm\\[xreg\\]`\\?","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/timesfm/utils/xreg_lib.py","lineNumber":26,"sourceCode":"#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Helper functions for in-context covariates and regression.\"\"\"\n\nimport itertools\nimport math\nfrom typing import Any, Iterable, Literal, Mapping, Sequence\n\ntry:\n  import jax\n  import jax.numpy as jnp\n  import numpy as np\n  from sklearn import preprocessing\nexcept ImportError:\n  raise ImportError(\n    \"Failed to load the XReg module. Did you forget to install `timesfm[xreg]`?\"\n  )\n\nCategory = int | str\n\n_TOL = 1e-6\nXRegMode = Literal[\"timesfm + xreg\", \"xreg + timesfm\"]\n\n\ndef _unnest(nested: Sequence[Sequence[Any]]) -> np.ndarray:\n  return np.array(list(itertools.chain.from_iterable(nested)))\n\n\ndef _repeat(elements: Iterable[Any], counts: Iterable[int]) -> np.ndarray:\n  return np.array(\n    list(itertools.chain.from_iterable(map(itertools.repeat, elements, counts)))\n  )\n","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/google-research/timesfm/blob/331c6d33cb1ac2611de3056d0ac7164aab6301eb/src/timesfm/utils/xreg_lib.py#L8-L44","documentation":"The xreg (external regression) utilities depend on JAX and scikit-learn, which are optional dependencies installed via the timesfm[xreg] extra. If importing jax or sklearn.preprocessing fails at module import time, this ImportError is raised to tell you to install the extra.","triggerScenarios":"Importing src/timesfm/utils/xreg_lib.py (directly or via covariates/xreg features) in an environment where jax or sklearn is not installed.","commonSituations":"Bare `pip install timesfm` (or `poetry add timesfm`) without the [xreg] extra; CI/minimal Docker images that omit optional deps; using covariate features like forecaster.forecast_with_covariates on a minimal install.","solutions":["Install the extra: pip install \"timesfm[xreg]\".","Or manually install missing deps: pip install jax scikit-learn.","Verify with `python -c \"import jax, sklearn\"` that the imports now succeed."],"exampleFix":"// before\npip install timesfm\n// after\npip install \"timesfm[xreg]\"","handlingStrategy":"try-catch","validationCode":"import importlib.util\nif importlib.util.find_spec(\"jax\") is None or importlib.util.find_spec(\"sklearn\") is None:\n    raise SystemExit(\"Install extras: pip install 'timesfm[xreg]'\")","typeGuard":"def xreg_available() -> bool:\n    import importlib.util\n    return importlib.util.find_spec(\"jax\") is not None and importlib.util.find_spec(\"sklearn\") is not None","tryCatchPattern":"try:\n    from timesfm.utils import xreg_lib\nexcept ImportError as e:\n    if \"XReg\" in str(e):\n        print(\"Run: pip install 'timesfm[xreg]'\")\n    else:\n        raise","preventionTips":["Always install timesfm with the [xreg] extra when using covariates","Pre-install extras in CI and Dockerfiles","Smoke-test imports (`import jax, sklearn`) in your deployment script"],"tags":["python","importerror","dependencies"],"backgroundTag":"missing-optional-dependency","analyzedSha":"331c6d33cb1ac2611de3056d0ac7164aab6301eb","analyzedAt":"2026-08-29T01:04:23.138Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}