Introduction

Installing TensorFlow in CPU-only mode is common for local development, CI jobs, and machines that do not have a supported CUDA setup. The safest approach is a clean virtual environment, one TensorFlow package strategy, and a small verification step that proves TensorFlow actually runs on the CPU.

Start With a Fresh Virtual Environment

TensorFlow brings a large dependency graph, so installation is much more reliable in an isolated environment than in a shared system interpreter.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel

This reduces version collisions with NumPy, protobuf, notebook tooling, and older TensorFlow remnants.

Pick One Package Strategy

On many current platforms, pip install tensorflow is enough even for CPU-only usage. TensorFlow will simply run on the CPU if no supported GPU runtime is available.

python -m pip install "tensorflow==2.16.1"

Some environments also expose tensorflow-cpu. If you choose that route, use it instead of tensorflow, not alongside it.

python -m pip install "tensorflow-cpu==2.16.1"

The important rule is to choose one package strategy and stick to it. Mixing package variants inside the same environment is a common way to create confusing import and dependency problems.

Verify More Than the Import

An import check is useful, but it is not enough. You want to confirm that TensorFlow imports, sees no GPU requirement, and can execute a real operation.

1import tensorflow as tf
2
3print("TensorFlow:", tf.__version__)
4print("GPUs:", tf.config.list_physical_devices("GPU"))
5
6x = tf.constant([[1.0, 2.0], [3.0, 4.0]])
7y = tf.matmul(x, x)
8print(y.numpy())

If this script runs and the GPU list is empty, you have a working CPU-only install.

Jupyter and IDEs Often Use the Wrong Interpreter

A very common failure pattern is that installation succeeded in the terminal but imports fail in Jupyter or the IDE. That usually means the tool is using a different Python interpreter.

Inside a notebook, confirm the active interpreter directly:

import sys
print(sys.executable)

If the path does not point to your virtual environment, install ipykernel there and register a matching notebook kernel instead of trying to patch the wrong environment.

Freeze a Working Setup

TensorFlow environments are sensitive to dependency drift. Once the installation works, freeze the exact dependency set.

python -m pip freeze > requirements-lock.txt

That gives you a reproducible baseline for teammates, CI, and future rebuilds. A tiny smoke-test script stored in the project is also worthwhile because it catches environment regressions before model code becomes the thing that fails.

CPU Tuning Is Optional but Real

CPU-only does not automatically mean unusable performance. TensorFlow exposes thread settings that can matter on multi-core systems.

1import tensorflow as tf
2
3tf.config.threading.set_intra_op_parallelism_threads(4)
4tf.config.threading.set_inter_op_parallelism_threads(2)

These values are workload-dependent, so treat them as tuning knobs rather than universal best defaults.

Know the Goal of a CPU-Only Install

A CPU-only setup is usually about reliability and simplicity, not raw training speed. It is a good fit for development, inference prototypes, teaching, unit tests, and environments where GPU setup would create more operational pain than value.

Once you frame it that way, the installation strategy becomes clearer: favor clean environments and reproducibility over clever package mixing.

Common Pitfalls

• Installing both tensorflow and tensorflow-cpu in the same environment.
• Validating only the import and never running a real tensor operation.
• Forgetting that notebooks and IDEs may use a different interpreter from the shell.
• Trying to debug TensorFlow before confirming the environment is actually isolated.
• Treating CPU-only setup as a half-broken GPU install instead of as a deliberate deployment choice.

Summary

• Use a clean virtual environment for TensorFlow CPU installs.
• Pick one package strategy and avoid mixing TensorFlow variants.
• Verify the installation with a real tensor operation, not only an import.
• Check the active interpreter in notebooks and IDEs.
• Freeze the working environment so the setup stays reproducible.