Introduction

This import error usually means your environment has conflicting Keras package paths or versions. In modern TensorFlow projects, the safest import is from tensorflow.keras, not standalone keras. A systematic environment check fixes the issue faster than repeated reinstall attempts.

Why the Error Happens

Historically, Keras existed both as standalone package and as TensorFlow-integrated API. Mixing both in one environment can make imports resolve to unexpected modules where to_categorical is missing or relocated.

Common problematic line:

from keras.utils import to_categorical

Preferred for TensorFlow workflows:

from tensorflow.keras.utils import to_categorical

Use one namespace consistently across the project.

Verify Active Interpreter and Package Paths

Check interpreter and pip target first.

1python -c "import sys; print(sys.executable)"
2python -m pip --version
3python -m pip show tensorflow keras
4python -m pip list | grep -E 'tensorflow|keras'

Then inspect import locations from Python:

1import tensorflow as tf
2import keras
3
4print(tf.__version__)
5print(keras.__file__)

If keras path points to an unexpected global site-packages folder, environment contamination is likely.

Clean Virtual Environment Fix

A fresh environment is often the fastest reliable solution.

1python -m venv .venv
2source .venv/bin/activate
3python -m pip install --upgrade pip
4python -m pip install tensorflow

Test import immediately:

from tensorflow.keras.utils import to_categorical
print(to_categorical([0, 2, 1], num_classes=3))

If this works, old environment state was the root problem.

Migrate Legacy Imports Safely

If codebase mixes keras.* and tensorflow.keras.*, do a focused migration PR:

1. Replace imports to one namespace.
2. Run unit and smoke training tests.
3. Compare output tensor shapes before and after.

Keep migration separated from architecture changes so regressions are easier to trace.

Notebook and Colab Gotchas

In notebook runtimes, package changes may not apply until kernel restart.

Recommended flow:

• Install dependencies.
• Restart runtime.
• Re-run imports from top.

Without restart, stale modules in memory can keep raising the same error even after correct installation.

End-to-End Validation Script

Run a tiny training pipeline to confirm import and functionality.

1import numpy as np
2import tensorflow as tf
3from tensorflow.keras.utils import to_categorical
4
5x = np.random.rand(20, 4).astype("float32")
6y = np.random.randint(0, 3, size=(20,))
7y_oh = to_categorical(y, num_classes=3)
8
9model = tf.keras.Sequential([
10    tf.keras.layers.Input(shape=(4,)),
11    tf.keras.layers.Dense(8, activation="relu"),
12    tf.keras.layers.Dense(3, activation="softmax")
13])
14model.compile(optimizer="adam", loss="categorical_crossentropy", metrics=["accuracy"])
15model.fit(x, y_oh, epochs=2, verbose=0)
16print("training ok")

This confirms import path, tensor conversion, and basic model compatibility.

Version and Locking Strategy

To avoid recurrence:

• Pin TensorFlow version in requirements or lock file.
• Avoid installing standalone keras unless your project explicitly requires it.
• Use one environment per project.

Reproducible environments are more important than ad hoc fixes.

A practical lock strategy is to pin TensorFlow major and minor version, then update intentionally through review so namespace shifts are caught in CI rather than in ad hoc notebook sessions.

Add a Fast Environment Sanity Check

You can fail early in CI with a tiny smoke script that verifies import path and runtime versions.

1import tensorflow as tf
2from tensorflow.keras.utils import to_categorical
3
4print("tensorflow", tf.__version__)
5print("to_categorical ok", to_categorical([0, 1], num_classes=2).shape)

Running this before training jobs catches broken environments quickly and prevents expensive long-running tasks from failing late.

Common Pitfalls

• Mixing keras and tensorflow.keras imports in one project.
• Installing packages into a different interpreter than execution runtime.
• Reusing polluted global Python environments for ML workloads.
• Skipping notebook runtime restart after dependency changes.
• Migrating imports and model logic in the same change, obscuring root causes.

Summary

• This error is usually an environment and namespace consistency problem.
• Prefer tensorflow.keras.utils.to_categorical in TensorFlow-based projects.
• Validate interpreter, pip target, and installed package paths first.
• Use clean virtual environments for deterministic behavior.
• Keep imports consistent and dependencies pinned to prevent repeat failures.