Keras

3.13.2 verified Tue May 12 auth: no python install: stale

Keras 3 is a multi-backend deep learning framework providing a high-level API for building and training neural networks. It supports JAX, TensorFlow, PyTorch, and OpenVINO (for inference-only) as computational backends, allowing users to leverage the same codebase across different frameworks. Focused on fast experimentation and user experience, Keras 3 enables efficient development and deployment of deep learning models across various domains. The current version is 3.13.2, and the library maintains an active release cadence with frequent updates.

pip install keras --upgrade

Common errors

error ModuleNotFoundError: No module named 'keras' ↓

cause In Keras 3, the standalone `keras` package is the default, and `tf.keras` is an alias provided for backward compatibility with TensorFlow 2.x. This error often occurs when the `keras` package itself is not installed, or there's a conflict between the standalone Keras 3 and `tf_keras` (which is Keras 2.x).

fix

Ensure Keras 3 is installed via pip install keras. If you intend to use the Keras 2.x API with TensorFlow, install tf_keras via pip install tf_keras and set the environment variable TF_USE_LEGACY_KERAS=1 or explicitly import from tf_keras. For new projects, directly import keras is recommended for Keras 3.

error ValueError: A KerasTensor cannot be used as input to a TensorFlow function. ↓

cause Keras 3 emphasizes backend-agnostic operations. Directly using TensorFlow-specific operations (e.g., `tf.sin()`, `tf.reduce_sum()`) on `KerasTensor` objects within a Keras functional model construction or custom layer's `call` method can cause this error because KerasTensors are symbolic placeholders for the chosen backend (JAX, TensorFlow, or PyTorch), not native TensorFlow tensors during graph construction.

fix

Replace TensorFlow API calls with their equivalent Keras Operations API (keras.ops.*). For example, use keras.ops.sin(x) instead of tf.sin(x), or keras.ops.sum(x) instead of tf.reduce_sum(x) to maintain backend compatibility.

error ValueError: Invalid filepath extension for saving. Please add either a `.keras` extension for the native Keras format (recommended) or a `.h5` extension. Use `model.export(filepath)` if you want to export a SavedModel for use with TFLite/TFServing/etc. ↓

cause Keras 3 changes the default model saving format and API. The `.tf` or un-suffixed SavedModel format is no longer directly supported by `model.save()` for Keras 3 models; it now expects `.keras` (native Keras 3 format) or `.h5` (legacy Keras 2 format). To export to the TensorFlow SavedModel format, a separate `model.export()` method is introduced.

fix

When saving, use model.save('my_model.keras') for the native Keras 3 format. If you need to export for TensorFlow Serving or TFLite, use model.export('path/to/saved_model'). When loading, use keras.models.load_model('my_model.keras') for native or H5 files. For loading a TensorFlow SavedModel as a Keras layer, use keras.layers.TFSMLayer(filepath, call_endpoint='serving_default').

error ValueError: Sequential model 'sequential_X' has no defined input shape yet. ↓

cause Keras Sequential models require the input shape to be explicitly defined for the very first layer. This error typically occurs when the `input_shape` argument is omitted or incorrectly specified in the first layer of a `Sequential` model.

fix

Provide the input_shape argument to the first layer in your Sequential model, or explicitly add a keras.Input layer as the first element. For example, model = keras.Sequential([keras.Input(shape=(input_dim,)), ...]) or model = keras.Sequential([keras.layers.Dense(units, input_shape=(input_dim,)), ...]).

error AttributeError: 'Tensor' object has no attribute 'numpy' ↓

cause This error arises when attempting to call the `.numpy()` method on a symbolic Keras tensor (which is a placeholder in a computation graph) rather than an eagerly executed concrete tensor. This commonly happens in custom layers or functions that mix graph-mode execution with eager-mode NumPy conversions.

fix

To convert a Keras tensor to a NumPy array within a graph context (like in a custom layer's call method during training), use tf.numpy_function (when using the TensorFlow backend) to wrap the NumPy operation. Alternatively, ensure eager execution is enabled globally if you are primarily working with eager tensors or evaluate the tensor within a tf.function with run_eagerly=True (though this can affect performance). When building backend-agnostic Keras code, prefer keras.ops.convert_to_numpy() or keras.ops.convert_to_tensor() for explicit conversions.

Warnings

breaking Keras 3.13.0 introduced a breaking change by requiring Python 3.11 or higher. Earlier Python versions are not supported. ↓

fix Upgrade your Python environment to version 3.11 or newer. `pip install --upgrade python` (if using pyenv/conda, manage environment accordingly).

gotcha The Keras backend (TensorFlow, JAX, or PyTorch) must be configured *before* importing Keras. Attempting to change it after import will not work. ↓

fix Set 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.

breaking Model 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. ↓

fix Use `model.save('my_model.keras')` for the native Keras format. For SavedModel/TFLite export, use `model.export(filepath)`.

gotcha When 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. ↓

fix For 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.

deprecated Setting 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. ↓

fix To ensure variables are tracked, use `self.add_weight()` within custom layers/models, or use `keras.Variable` instead of `tf.Variable`.

gotcha Security hardening was introduced to disallow `TFSMLayer` deserialization in `safe_mode`, preventing potential execution of attacker-controlled graphs during model loading from external TensorFlow SavedModels. ↓

fix Upgrade to Keras 3.12.1, 3.13.2, or newer to benefit from this security fix. Avoid loading untrusted models.

breaking Installing 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. ↓

fix Install 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.

Install

pip install tensorflow # for TensorFlow backend
pip install jax jaxlib # for JAX backend
pip install torch torchvision torchaudio # for PyTorch backend

Install compatibility stale last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) keras build_error - - - -

3.10 alpine (musl) keras - - - -

3.10 alpine (musl) tensorflow no_wheel - - - -

3.10 alpine (musl) tensorflow - - - -

3.10 slim (glibc) keras wheel 6.4s - 156M

3.10 slim (glibc) keras - - - -

3.10 slim (glibc) tensorflow - - - -

3.11 alpine (musl) keras build_error - - - -

3.11 alpine (musl) keras - - - -

3.11 alpine (musl) tensorflow no_wheel - - - -

3.11 alpine (musl) tensorflow - - - -

3.11 slim (glibc) keras wheel 6.2s - 169M

3.11 slim (glibc) keras - - - -

3.11 slim (glibc) tensorflow - - - -

3.12 alpine (musl) keras build_error - - - -

3.12 alpine (musl) keras - - - -

3.12 alpine (musl) tensorflow no_wheel - - - -

3.12 alpine (musl) tensorflow - - - -

3.12 slim (glibc) keras wheel 6.1s - 158M

3.12 slim (glibc) keras - - - -

3.12 slim (glibc) tensorflow - - - -

3.13 alpine (musl) keras build_error - - - -

3.13 alpine (musl) keras - - - -

3.13 alpine (musl) tensorflow no_wheel - - - -

3.13 alpine (musl) tensorflow - - - -

3.13 slim (glibc) keras wheel 6.4s - 157M

3.13 slim (glibc) keras - - - -

3.13 slim (glibc) tensorflow - - - -

3.9 alpine (musl) keras build_error - - - -

3.9 alpine (musl) keras - - - -

3.9 alpine (musl) tensorflow no_wheel - - - -

3.9 alpine (musl) tensorflow - - - -

3.9 slim (glibc) keras wheel 7.2s - 164M

3.9 slim (glibc) keras - - - -

3.9 slim (glibc) tensorflow timeout - - - -

3.9 slim (glibc) tensorflow - - - -

Imports

Model
wrong
```
from tensorflow.keras import Model
```
correct
```
from 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
wrong
```
from tensorflow.keras import layers
```
correct
```
from keras import layers
```
Similar to `Model`, layers and other Keras components should be imported directly from the `keras` namespace for Keras 3.x.

Quickstart last tested: 2026-04-24

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}")