google-research/timesfm · error · ImportError

Failed to load the XReg module. Did you forget to install `t

Error message

Failed to load the XReg module. Did you forget to install `timesfm[xreg]`?

What it means

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.

Source

Thrown at src/timesfm/utils/xreg_lib.py:26

#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Helper functions for in-context covariates and regression."""

import itertools
import math
from typing import Any, Iterable, Literal, Mapping, Sequence

try:
  import jax
  import jax.numpy as jnp
  import numpy as np
  from sklearn import preprocessing
except ImportError:
  raise ImportError(
    "Failed to load the XReg module. Did you forget to install `timesfm[xreg]`?"
  )

Category = int | str

_TOL = 1e-6
XRegMode = Literal["timesfm + xreg", "xreg + timesfm"]


def _unnest(nested: Sequence[Sequence[Any]]) -> np.ndarray:
  return np.array(list(itertools.chain.from_iterable(nested)))


def _repeat(elements: Iterable[Any], counts: Iterable[int]) -> np.ndarray:
  return np.array(
    list(itertools.chain.from_iterable(map(itertools.repeat, elements, counts)))
  )

View on GitHub (pinned to 331c6d33cb)

Solutions

1. Install the extra: pip install "timesfm[xreg]".
2. Or manually install missing deps: pip install jax scikit-learn.
3. Verify with `python -c "import jax, sklearn"` that the imports now succeed.

Example fix

// before
pip install timesfm
// after
pip install "timesfm[xreg]"

import importlib.util
if importlib.util.find_spec("jax") is None or importlib.util.find_spec("sklearn") is None:
    raise SystemExit("Install extras: pip install 'timesfm[xreg]'")

def xreg_available() -> bool:
    import importlib.util
    return importlib.util.find_spec("jax") is not None and importlib.util.find_spec("sklearn") is not None

try:
    from timesfm.utils import xreg_lib
except ImportError as e:
    if "XReg" in str(e):
        print("Run: pip install 'timesfm[xreg]'")
    else:
        raise

When it happens

Trigger: Importing src/timesfm/utils/xreg_lib.py (directly or via covariates/xreg features) in an environment where jax or sklearn is not installed.

Common situations: 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.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• Model is not compiled. Please call compile() first.
• For XReg, `return_backcast` must be set to True in the forec
• At least one of dynamic_numerical_covariates, dynamic_catego
• Unsupported mode: {xreg_mode}
• Forecast horizon length inferred from the dynamic covariates

AI-assisted analysis of google-research/timesfm@331c6d33cb (2026-08-29). Data as JSON: /api/errors/fcf9c629bc472cd1. Report an issue: GitHub.