Introduction

tensorflow-text is a companion package that adds tokenizers and other text-processing ops that are not bundled into core TensorFlow. The key installation rule is version matching: the TensorFlow Text package should use the same major and minor version as the TensorFlow package in your environment.

Install into a Clean Virtual Environment

The safest approach is to create a fresh virtual environment, upgrade pip, install TensorFlow, and then install the matching TensorFlow Text wheel.

1python -m venv .venv
2source .venv/bin/activate
3python -m pip install --upgrade pip
4python -m pip install tensorflow
5
6TF_MM=$(python -c "import tensorflow as tf; print('.'.join(tf.__version__.split('.')[:2]))")
7python -m pip install "tensorflow-text==${TF_MM}.*"

That shell snippet installs TensorFlow first, reads the installed major and minor version, and then installs the corresponding TensorFlow Text release. Matching versions matters because TensorFlow Text contains compiled extensions that must line up with the TensorFlow binary already in the environment.

Verify the Installation

After installation, confirm that both imports work in the same interpreter:

1python - <<'PY'
2import tensorflow as tf
3import tensorflow_text as text
4
5print("TensorFlow:", tf.__version__)
6print("TensorFlow Text loaded from:", text.__file__)
7PY

If both imports succeed, the package is installed correctly enough for normal development work.

Why Version Mismatch Causes Trouble

TensorFlow Text is not a pure Python package. It ships compiled ops, so minor-version mismatches are a common cause of import failures. Installing the newest tensorflow-text blindly on top of an older TensorFlow build can lead to runtime errors that look unrelated until you compare versions.

A practical rule is:

• install TensorFlow first
• read its version
• install the same TensorFlow Text major and minor series

That is more reliable than guessing.

Platform Notes

TensorFlow's official installation guidance changes by platform. For example, TensorFlow currently documents no official GPU support on macOS, and native Windows GPU support ended after TensorFlow 2.10, with newer GPU workflows going through WSL2 instead. Those platform details affect TensorFlow first, and TensorFlow Text inherits the same environment constraints because it depends on the TensorFlow runtime underneath.

If a matching tensorflow-text wheel is unavailable for your Python version or platform, pip may fail even though TensorFlow itself installed successfully. That situation is common with packages that include custom C++ extensions.

Building from Source When Wheels Are Not Available

The TensorFlow Text documentation explains that source builds should happen in the same environment as TensorFlow. If you must build from source, install or build TensorFlow first, then build TensorFlow Text against that environment.

git clone https://github.com/tensorflow/text.git
cd text
./oss_scripts/run_build.sh

The official guide specifically notes that macOS source builds need coreutils installed and recommends building TensorFlow from source first. Source builds are more work, but they are often the fallback on unsupported platforms.

Common Pitfalls

The most common mistake is ignoring version alignment and installing different TensorFlow and TensorFlow Text minor versions. That is the first thing to check when the import fails.

Another issue is mixing environments. If pip installs into one virtual environment and python runs from another, the package may appear to install successfully but still fail to import.

Platform support is another trap. A wheel may exist for Linux but not for your exact Python version on macOS or Windows, especially when compiled extensions are involved.

Finally, verify the package name. The pip package is tensorflow-text, while the Python import is tensorflow_text.

Summary

• Install TensorFlow first, then install the matching tensorflow-text major and minor version.
• Use a clean virtual environment to avoid cross-environment import problems.
• Verify installation by importing both tensorflow and tensorflow_text in the same interpreter.
• If no wheel exists for your platform, build TensorFlow Text from source in the same environment as TensorFlow.
• Remember that the pip package name uses a hyphen, while the Python module name uses an underscore.