Install & Compatibility
Where this runs
tested against v3.12.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ no_wheel
1/2 runs
152MB installed
● package 152MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Model
✓ from keras import Model
✗ from tensorflow.keras import Model
Keras 3.x is imported directly as `keras`. While `tf.keras` can point to Keras 3 in TensorFlow 2.16+, direct `import keras` is recommended for explicit Keras 3 usage and backend-agnostic development.
layers
✓ from keras import layers
✗ from tensorflow.keras import layers
Similar to `Model`, layers and other Keras components should be imported directly from the `keras` namespace for Keras 3.x.
This quickstart demonstrates building, compiling, and training a simple convolutional neural network using Keras 3.x for image classification on the MNIST dataset. It includes setting the backend via an environment variable before importing Keras, which is a critical step for Keras 3.x.
import os
os.environ["KERAS_BACKEND"] = os.environ.get("KERAS_BACKEND", "tensorflow") # Set backend before importing keras
import keras
from keras import layers
import numpy as np
# Load example data (e.g., MNIST for a simple classification task)
(x_train, y_train), (x_test, y_test) = keras.datasets.mnist.load_data()
x_train = x_train.reshape(-1, 28, 28, 1).astype("float32") / 255.0
x_test = x_test.reshape(-1, 28, 28, 1).astype("float32") / 255.0
# Define a simple Sequential model
model = keras.Sequential([
keras.Input(shape=(28, 28, 1)),
layers.Conv2D(32, kernel_size=(3, 3), activation="relu"),
layers.MaxPooling2D(pool_size=(2, 2)),
layers.Conv2D(64, kernel_size=(3, 3), activation="relu"),
layers.MaxPooling2D(pool_size=(2, 2)),
layers.Flatten(),
layers.Dropout(0.5),
layers.Dense(10, activation="softmax"),
])
# Compile the model
model.compile(
loss=keras.losses.SparseCategoricalCrossentropy(),
optimizer=keras.optimizers.Adam(learning_rate=1e-3),
metrics=["accuracy"],
)
# Train the model
print("\nTraining model...")
model.fit(x_train, y_train, batch_size=128, epochs=3, validation_split=0.1)
# Evaluate the model
print("\nEvaluating model...")
loss, accuracy = model.evaluate(x_test, y_test)
print(f"Test Loss: {loss:.4f}, Test Accuracy: {accuracy:.4f}")
Debug
Known issues
breakingKeras 3.13.0 introduced a breaking change by requiring Python 3.11 or higher. Earlier Python versions are not supported.fixUpgrade your Python environment to version 3.11 or newer. `pip install --upgrade python` (if using pyenv/conda, manage environment accordingly).
affects: >=3.13.0
gotchaThe Keras backend (TensorFlow, JAX, or PyTorch) must be configured *before* importing Keras. Attempting to change it after import will not work.fixSet the `KERAS_BACKEND` environment variable (e.g., `os.environ["KERAS_BACKEND"] = "jax"`) or configure `~/.keras/keras.json` before any `import keras` statement in your code.
affects: All Keras 3.x versions
breakingModel saving in Keras 3.x has changed. The `model.save()` method now expects the native Keras `.keras` format. Saving to the TensorFlow SavedModel format directly via `model.save()` is no longer supported and will raise a ValueError.fixUse `model.save('my_model.keras')` for the native Keras format. For SavedModel/TFLite export, use `model.export(filepath)`. affects: All Keras 3.x versions
gotchaWhen using TensorFlow versions 2.0 through 2.15, `pip install tensorflow` would install Keras 2.x and make it available via `import keras` and `tf.keras`. If you install TensorFlow 2.15, it will overwrite a Keras 3 installation with Keras 2.15.fixFor TensorFlow versions <=2.15, if you intend to use Keras 3, you must reinstall Keras 3 *after* installing TensorFlow 2.15. TensorFlow 2.16+ installs Keras 3 by default, but direct `import keras` is still recommended for clarity.
affects: TensorFlow <=2.15 when used with Keras 3.x
deprecatedSetting a `tf.Variable` directly as an attribute of a Keras 3 layer or model will no longer automatically track that variable as a trainable weight, unlike in Keras 2.fixTo ensure variables are tracked, use `self.add_weight()` within custom layers/models, or use `keras.Variable` instead of `tf.Variable`.
affects: All Keras 3.x versions
gotchaSecurity hardening was introduced to disallow `TFSMLayer` deserialization in `safe_mode`, preventing potential execution of attacker-controlled graphs during model loading from external TensorFlow SavedModels.fixUpgrade to Keras 3.12.1, 3.13.2, or newer to benefit from this security fix. Avoid loading untrusted models.
affects: <3.12.1 and <3.13.2
breakingInstalling Keras 3.x on Alpine Linux or similar minimal environments may fail due to missing build tools (e.g., g++, cmake) required to compile its dependencies (`ml-dtypes`, `optree`). These environments typically do not include development packages by default, leading to 'command 'g++' failed' or 'CMake Error' during wheel building.fixInstall necessary build tools before attempting to install Keras. For Alpine, this usually means `apk add build-base cmake`. For other distributions, use their respective package managers (e.g., `apt-get install build-essential cmake` on Debian/Ubuntu, `yum install gcc-c++ make cmake` on RHEL/CentOS). Alternatively, consider using a full Linux distribution image (e.g., `python:3.13-slim` or `python:3.13`) instead of Alpine for environments where C extensions are common.
affects: All Keras 3.x versions when installed on minimal Linux distributions (e.g., Alpine)
Upgrade
Version history
3.15.1latest on PyPI · released Jul 29, 2026
Audit
Dependencies
pythonrequiredKeras 3.13.0 and later requires Python 3.11 or higher.
tensorflowoptionalOne of the optional computational backends for Keras 3.x. Minimum supported version is 2.16.1.
jaxoptionalOne of the optional computational backends for Keras 3.x. Minimum supported version is 0.4.20.
torchoptionalOne of the optional computational backends for Keras 3.x. Minimum supported version is 2.1.0.
openvinooptionalOptional backend for inference-only operations with Keras 3.x. Minimum supported version is 2025.3.0.