TensorFlow: installing the pip package and training a first model

What TensorFlow solves and who the repository is written for

The README describes TensorFlow as an end-to-end open source platform for machine learning, with a set of tools, libraries and community resources. The scope claim matters more than the wording: the same project covers model authoring, training and deployment, and the repository reflects that breadth in its top-level layout, which holds a tensorflow/ source tree, a third_party/ directory, a ci/ directory and a tools/ directory alongside the Bazel build files BUILD, WORKSPACE and MODULE.bazel.

The intended audience is split. Researchers get the Python API, which the README calls stable, and developers get the same Python surface plus a stable C++ API for serving and embedding. The README also notes a non-guaranteed backward compatible API for other languages, which is a candid admission that the Python and C++ surfaces are the ones the project treats as contracts. If you are picking a framework for a Python data pipeline or a C++ inference service, you are inside the supported envelope. If you are picking it because you want a binding for a language outside that pair, you are outside it, and the README says so rather than pretending otherwise.

How the framework is put together in the repository

TensorFlow is a C++ project with a Python front end. The primary language listed for the repository is C++, and the Python package is a binding over that core, which is why the build story is Bazel rather than setuptools alone. The .bazelrc, .bazelversion and bazel_downloader.cfg files at the top level are the build configuration, and configure.py is the script that generates a local build configuration before a source build. That arrangement tells you something practical: a source build is a Bazel build, and the install guide's source page is the only supported route to one.

Data flow in the normal case is simple. You describe a computation, TensorFlow builds a graph of operations, and execution happens on whatever device the runtime selects. The README's first example makes the eager path visible: tf.add(1, 2).numpy() returns 3, and tf.constant('Hello, TensorFlow!').numpy() returns b'Hello, TensorFlow!'. Calling .numpy() on a tensor converts it to a NumPy value, which is the boundary most Python users cross constantly. Device selection is not in the README; the install guide owns GPU enablement, and for DirectX and macOS Metal the README points at Device Plugins rather than claiming built-in support.

Installing TensorFlow with pip and running a first training step

The README's install section does not inline the full instructions. It points to the TensorFlow install guide for the pip package, GPU support, Docker containers and source builds. The two commands it does give are the current release and the CPU-only variant. Run the first if you want the default package, and note that the README scopes CUDA-enabled GPU support to Ubuntu and Windows.

pip install tensorflow

If you do not need GPU code paths and want a smaller package, the README gives a second command. The same section says to add --upgrade to either command to move to the latest version.

pip install tensorflow-cpu

After installation, the README's own first program is a REPL session rather than a script. Start Python and check that the import resolves and that eager execution returns a value you can read back.

import tensorflow as tf
tf.add(1, 2).numpy()
hello = tf.constant('Hello, TensorFlow!')
hello.numpy()

The expected results are 3 and b'Hello, TensorFlow!'. If the import fails, the problem is almost always the wheel and interpreter pairing, not the library. The repository carries requirements_lock_3_10.txt through requirements_lock_3_14.txt plus requirements_lock_3_14_freethreaded.txt, which shows the project tracks several Python versions at once; match your interpreter to a wheel that exists for it before debugging anything else.

For a real training run, the README does not include an example, so the honest next step is the tutorial index it links, https://www.tensorflow.org/tutorials/. That page, not the README, is where model definition, compilation and fitting are documented.

Where TensorFlow stops being the right choice

The README makes a claim that is easy to misread. It says TensorFlow is an end-to-end platform, which is true at the project level, but the repository is not a single product. A GPU build, a CPU-only build, a Docker image and a source build are four different things with four different failure modes, and the README delegates all four to the install guide. If your constraint is a small dependency footprint or a reproducible build you can audit in an afternoon, the Bazel-based source path is a poor fit, and the CPU-only pip package is the only concession the README offers.

The second limit is version coupling. The README documents a patching procedure for a specific release: clone the repository, switch to the branch for that version (it gives r2.8 for version 2.8 as the example), cherry-pick the changes, run the tests, then build the pip package from source. That is the supported way to patch a release, and it means a security fix on an older minor version is a build exercise, not a package upgrade. Teams that expect to stay on a pinned version for years should budget for that.

The third limit is the language surface. Only Python and C++ are described as stable. Anything else sits behind the non-guaranteed backward compatible API, which is a reasonable engineering position and a bad foundation for a product that depends on it.

TensorFlow against PyTorch, and how the two differ in practice

The most common comparison question about this project is TensorFlow versus PyTorch, and the repository itself does not answer it. What the repository does show is an architecture built around a C++ core with a compiled graph execution model, plus a Bazel build and a separate deployment story that the README extends to browsers and edge devices through Device Plugins and TensorFlow Lite. That is a framework shaped by the assumption that the same model will be trained on a server and shipped somewhere smaller.

PyTorch's defining choice is the opposite emphasis: eager execution as the primary mode and a Python-first authoring experience, with deployment handled by separate export paths. TensorFlow 2.x moved toward eager execution and the README's own example uses it, so the day-to-day authoring gap is narrower than it was. The remaining difference is where the project spends its complexity. TensorFlow spends it on the build system, the multi-language API surface and the device matrix. If you never leave Python and never deploy off a server, you are paying for capability you will not use. If you do deploy to browsers or edge hardware, that is exactly the capability you are buying.

Release cadence, upgrade cost and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-03-06, the same date as the v2.21.0 release. The two release candidates, v2.21.0-rc1 on 2026-03-02 and v2.21.0-rc0 on 2026-02-09, show the release process running through candidates before the final tag. That is a normal cadence for a project of this size, and it also means the release candidates are the early signal for anything that will break in the next minor version. If you pin a version, watch the rc tags rather than the final tag.

Upgrade cost is dominated by two things the README makes explicit. First, the stable Python and C++ APIs are the compatibility promise, so code that stays inside them is the code that upgrades cheaply. Second, the patching guidelines describe a cherry-pick-and-rebuild workflow for a released version, which is the only documented way to get a fix onto an older branch. Upgrading across a minor version is a pip operation; staying on an old minor version with backported fixes is a build operation.

The licence is Apache-2.0, stated in the repository's LICENSE file and repeated in the project metadata. Apache-2.0 is a permissive licence with an explicit patent grant, and it does not require you to publish your own code. That is a summary of the licence identifier, not legal advice; if you are redistributing a modified build, read the licence text and your own counsel's guidance.

Editorial conclusion

Adopt TensorFlow if you need a stable Python and C++ API with deployment targets that include servers, browsers and edge devices, and if you are willing to pin a release rather than track master. Do not adopt it if you want a single small dependency or if your team already standardised on another framework's training loop; the migration cost is real and the README offers no migration tooling. Verify first that the pip wheel matches your Python version, since the repository ships separate requirements_lock files for 3.10 through 3.14 plus a freethreaded variant, and confirm your GPU path against the install guide before promising a deadline.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes