Coexisting tf.keras and standalone Keras 3 in one project: dependency and import strategy

Answer to the core questions

1. Should we pin standalone keras and ban tf.keras? In TensorFlow 2.16+, tf.keras is an alias that points to the same Keras 3 code base when the KERAS_BACKEND is set to tensorflow. However, if the alias is resolved to a different package instance (e.g., because keras==2.x is pulled by a transitive dependency), model and layer objects become incompatible. The safest practice is to pin keras==3.x and tensorflow==2.16.x in all dependency manifests and to use a single import style—preferably import keras—throughout the project. Third‑party packages that still use from tensorflow import keras will share the same instance under these pinning rules.
2. What dependency‑pinning strategy prevents silent conflicts? Specify exact major, minor, and patch numbers for both tensorflow and keras in every requirements file (e.g., tensorflow==2.16.1, keras==3.2.1) and audit indirect dependencies for other keras pulls. A lock file (pip‑freeze, Poetry lock) or a CI step that runs pip check can surface mismatches before deployment.
3. Is converting .h5 to .keras mandatory? No, Keras 3 can read .h5 checkpoints as long as the custom layers used in the model are registered via custom_objects. During a transition window you can keep both formats, but for long‑term maintainability and to avoid custom‑object registration headaches, converting to the native .keras format is recommended.

Confirmed facts (based on current TF 2.16+ behavior)

• In TF 2.16+, tf.keras is a lightweight wrapper that imports the same modules as standalone keras when KERAS_BACKEND is set to tensorflow.
• Different package instances (e.g., keras==2.x vs keras==3.x) lead to non‑interchangeable model objects.
• Loading a .h5 file with Keras 3 requires custom_objects for any custom layer defined with TF‑only symbols.

Practical steps for this project

1. Pin versions in pyproject.toml or requirements.txt:

   tensorflow==2.16.1
   keras==3.2.1

2. Set the backend once, before any imports:

   export KERAS_BACKEND=tensorflow

3. Replace any from tensorflow import keras imports in your own code with import keras.
4. For third‑party libraries that cannot be changed, rely on the shared instance provided by the pinning strategy.
5. During the migration window, keep both .h5 and .keras artifacts; after conversion, deprecate the .h5 loader.

Missing diagnostic detail that could change the recommendation

Do any of your custom layers use TensorFlow‑only symbols (e.g., tf.nn or tf.keras.layers.Conv2D) inside their call methods? If so, a non‑TensorFlow backend would require rewriting those layers to use keras.ops or a compatible abstraction.