Install & Compatibility
Where this runs
tested against v2.21.0 · 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
6533MB installed
● package 6533MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
keras
✓ # Option 1: Use standalone Keras 3 (recommended for new code)
import keras
model = keras.Sequential([keras.layers.Dense(64, activation='relu')])
# Option 2: Access via tf.keras (same Keras 3 in TF 2.16+)
import tensorflow as tf
model = tf.keras.Sequential([tf.keras.layers.Dense(64)])
✗ # Mixing tf.keras and keras objects causes ValueError:
import keras
import tensorflow_hub as hub
layer = hub.KerasLayer(url) # hub uses tf.keras, not standalone keras
model = keras.Sequential([layer]) # ValueError: not a keras.Layer instance
Since TF 2.16, tf.keras and import keras both point to Keras 3 — but third-party libraries like tensorflow_hub, tensorflow_probability may still use the old bundled keras, causing isinstance failures.
tf.function
✓ @tf.function
def train_step(x, y):
with tf.GradientTape() as tape:
pred = model(x, training=True)
loss = loss_fn(y, pred)
grads = tape.gradient(loss, model.trainable_variables)
optimizer.apply_gradients(zip(grads, model.trainable_variables))
return loss
✗ # Calling model.fit() for a single step — inefficient
# Using sess.run() — TF 1.x session API removed in TF 2.0
TF 1.x session-based API (sess = tf.Session(), sess.run()) fully removed in TF 2.0. Use eager execution or @tf.function for graph compilation.
Keras 3 model with TensorFlow backend. Use .keras format for saving.
import tensorflow as tf
import keras
# Build model (Keras 3)
model = keras.Sequential([
keras.layers.Dense(64, activation='relu', input_shape=(10,)),
keras.layers.Dense(1)
])
model.compile(
optimizer='adam',
loss='mse',
metrics=['mae']
)
# Train
model.fit(X_train, y_train, epochs=10, batch_size=32, validation_split=0.2)
# Save / load (.keras format recommended)
model.save('model.keras')
loaded = keras.models.load_model('model.keras')
Debug
Known issues
breakingTF 2.16+ ships Keras 3 as default. tf.keras now points to Keras 3, which has breaking API differences from Keras 2. Code written for Keras 2 (tf.keras with TF <2.16) may fail silently or with cryptic errors.fixTo keep Keras 2: pip install tf-keras, then set environment variable TF_USE_LEGACY_KERAS=1 before any tensorflow import. For new code, migrate to Keras 3 API. Key changes: tf.Variable attributes → keras.Variable, TF SavedModel save/load API changed, jit_compile=True by default.
affects: >= 2.16
breakingtf.estimator API fully removed in TF 2.16. Any code using tf.estimator.Estimator, tf.estimator.DNNClassifier, etc. raises AttributeError.fixMigrate to Keras model API. The Keras training API (model.fit, model.evaluate, model.predict) covers all use cases from tf.estimator.
affects: >= 2.16
breakingKeras 3: model.save() to TF SavedModel format no longer supported. model.save('path') now saves in .keras format by default.fixUse model.save('model.keras') for Keras format. To export as TF SavedModel: tf.saved_model.save(model, 'saved_model_dir'). To load a SavedModel as a Keras layer: keras.layers.TFSMLayer('saved_model_dir', call_endpoint='serving_default'). affects: >= Keras 3.0 / TF 2.16
breakingKeras 3: tf.Variable assigned as Layer attributes is NOT tracked as a weight. This silently breaks custom layers that assign tf.Variable in __init__.fixUse self.add_weight() or assign keras.Variable instead of tf.Variable for tracked layer weights.
affects: >= Keras 3.0 / TF 2.16
breakingWindows: TF GPU support above 2.10 dropped for Windows Native. tensorflow>=2.11 on Windows only runs on CPU. GPU on Windows requires WSL2.fixUse tensorflow<2.11 for native Windows GPU, or use WSL2 for GPU support with newer versions.
affects: >= 2.11 on Windows
gotchaMixing standalone keras package and tf.keras objects causes isinstance failures. Libraries like tensorflow_hub use tf.keras internally — adding hub.KerasLayer to a standalone keras.Sequential raises ValueError: not an instance of keras.Layer.fixUse consistent imports: either always use tf.keras (from tensorflow import keras) or always use standalone import keras. Do not mix objects from both in the same model.
affects: >= 2.16
gotchaKeras 3 sets jit_compile=True by default (XLA compilation). Custom layers using TensorFlow-specific ops not supported by XLA will silently fail or error. Was False by default in Keras 2.fixPass jit_compile=False to model.compile() if you encounter XLA errors with custom layers or TF ops.
affects: >= Keras 3.0
breakingTensorFlow often lacks pre-built wheels for very new Python versions (e.g., Python 3.13) or non-standard Linux distributions like Alpine (due to musl libc). This results in 'No matching distribution found' errors during installation.fixUse a supported Python version (e.g., Python 3.9-3.11 for TensorFlow 2.x) and a glibc-based Linux distribution (e.g., Ubuntu, Debian, CentOS) or their official Docker images for TensorFlow installation.
affects: >= Python 3.13 or Alpine Linux
Upgrade
Version history
2.21.0latest on PyPI · released Mar 6, 2026
Audit
Dependencies
keras>=3.0requiredKeras 3 is the default Keras since TF 2.16. Installed automatically. Now a separate package from tensorflow.
tf-kerasoptionalKeras 2 compatibility shim. Install if you need Keras 2 API with TF 2.16+. Maintenance mode only — no new features.