Install & Compatibility
Where this runs
tested against v1.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.532s · 20.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.072s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
schema_pb2
✓ from tensorflow_metadata.proto.v0 import schema_pb2
✗ from tf_metadata.proto.v0 import schema_pb2
This quickstart demonstrates how to define a simple data schema using `tensorflow-metadata`'s protobuf definitions. It shows how to add features with different types and constraints, then serializes and deserializes the schema for storage or transfer.
from tf_metadata.proto.v0 import schema_pb2
# Create a simple schema definition
schema = schema_pb2.Schema()
# Add a feature named 'age' of type INT
feature_age = schema.feature.add()
feature_age.name = "age"
feature_age.type = schema_pb2.FeatureType.INT
feature_age.int_domain.is_categorical = False
feature_age.presence.min_fraction = 1.0 # 'age' must always be present
feature_age.int_domain.min = 0
feature_age.int_domain.max = 120
# Add a feature named 'city' of type BYTES (string), which is categorical
feature_city = schema.feature.add()
feature_city.name = "city"
feature_city.type = schema_pb2.FeatureType.BYTES
feature_city.string_domain.is_categorical = True
feature_city.string_domain.value.extend(["New York", "London", "Tokyo"])
print("Generated Schema (protobuf format):")
print(schema)
# Serialize the schema to bytes
serialized_schema = schema.SerializeToString()
print(f"\nSerialized Schema (bytes): {len(serialized_schema)} bytes")
# Deserialize the schema back from bytes
deserialized_schema = schema_pb2.Schema()
deserialized_schema.ParseFromString(serialized_schema)
print("\nDeserialized Schema:")
print(deserialized_schema)
Debug
Known issues
breakingFrequent and critical dependency conflicts with the `protobuf` library. `tensorflow-metadata` often pins `protobuf` to specific major/minor versions, which can clash with other libraries in the TensorFlow ecosystem.fixConsult `tensorflow-metadata`'s `setup.py` or `RELEASE.md` for exact `protobuf` version requirements for your Python version (e.g., `protobuf>=4.25.2,<5` for Python 3.11). Consider using a virtual environment and carefully managing dependencies.
affects: All versions, especially when used in complex environments.
deprecatedSupport for Python 3.8 was deprecated starting from version 1.15.0.fixUpgrade to Python 3.9 or higher. The library currently supports Python >=3.9,<4.
affects: 1.15.0 and later.
gotchaNightly builds of `tensorflow-metadata` (and related TF projects) are explicitly stated to be unstable and prone to breakages, with fixes potentially taking a week or more.fixAlways use the stable versions available on PyPI (`pip install tensorflow-metadata`) for production or reliable development. Only use nightly builds if you need the absolute latest features and are prepared to handle instability.
affects: Nightly builds.
breakingVersion 1.15.0 introduced a semantic change to how `min/max/avg/tot num-values` are calculated for nested features, now relying on the innermost level.fixIf you rely on statistics for nested features, re-evaluate existing pipelines and logic when upgrading to 1.15.0 or later, as the reported values might change.
affects: 1.15.0 and later.
breakingThe field `NaturalLanguageDomain.location_constraint_regex` was removed in version 1.15.0. It was previously documented as 'please do not use' and was never fully implemented.fixRemove any usage of `NaturalLanguageDomain.location_constraint_regex` from your code.
affects: 1.15.0 and later.
Upgrade
Version history
1.21.0latest on PyPI · released Jun 9, 2026
Audit
Dependencies
protobufrequiredCrucial for defining and serializing metadata schemas and statistics. Often a source of version conflicts in the TensorFlow ecosystem.
absl-pyrequiredUsed for various foundational utilities within the TensorFlow ecosystem.
googleapis-common-protosrequiredProvides common protobuf definitions shared across Google APIs and projects.