How to Install TensorFlow on Ubuntu

This guide walks you through installing TensorFlow on Ubuntu, the most common Linux distribution for machine learning. You’ll learn how to set up a Python virtual environment, install TensorFlow with pip, and verify the installation works with your GPU (if you have one). By the end, you’ll have a working TensorFlow setup ready for your projects.

What You’ll Need

Ubuntu 20.04 or newer (64-bit)
Python 3.8–3.12 (check with python3 --version)
pip for Python 3 (install with sudo apt install python3-pip if missing)
An NVIDIA GPU with compute capability 3.5+ for GPU support (optional)
NVIDIA drivers and CUDA toolkit for GPU support (optional, see steps)
At least 4 GB of free disk space

Step-by-Step

Update your system – Open a terminal and run:
```
sudo apt update
sudo apt upgrade
```
This ensures your package list is current and all existing software is up to date.
Install Python and pip – If Python 3 is not installed, or pip is missing:
```
sudo apt install python3 python3-pip python3-venv
```
Verify with python3 --version and pip3 --version.
Create a virtual environment – It’s best practice to isolate TensorFlow and its dependencies from your system Python:
```
python3 -m venv tf-env
```
This creates a folder named tf-env in your current directory.
Activate the environment – Run:
```
source tf-env/bin/activate
```
Your terminal prompt should now show (tf-env) at the beginning, indicating the environment is active.
Upgrade pip inside the environment – Always use the latest pip to avoid dependency issues:
```
pip install --upgrade pip
```
Install TensorFlow – For the CPU-only version (works on any machine):
```
pip install tensorflow
```
If you have an NVIDIA GPU and want to use it, install the GPU-enabled package instead:
```
pip install tensorflow[and-cuda]
```
This automatically installs CUDA and cuDNN libraries via pip (TensorFlow 2.11+), so you don’t need to manually install them.
Verify the installation – With the environment still active, run:
```
python -c "import tensorflow as tf; print(tf.__version__)"
```
You should see the version number (e.g., 2.16.1). If you installed the GPU version, also run:
```
python -c "print(tf.config.list_physical_devices('GPU'))"
```
This should list your GPU if it’s detected.
Test a simple computation – Create a small script or run:
```
python -c "import tensorflow as tf; print(tf.constant('Hello TensorFlow'))"
```
If it prints the string without errors, your installation is functional.
Deactivate the environment when done – Run deactivate to leave the virtual environment.

Common Mistakes

Installing TensorFlow globally – Using sudo pip install tensorflow can conflict with system packages and cause permission errors. Always use a virtual environment.
Using Python 2 – TensorFlow requires Python 3. Check your Python version before installing.
Forgetting to activate the environment – If you get a ModuleNotFoundError, you likely forgot to run source tf-env/bin/activate.
Mixing CPU and GPU packages – Installing both tensorflow and tensorflow-gpu (in older versions) can cause conflicts. Use only one.
Ignoring CUDA version requirements – For GPU support, your NVIDIA driver and CUDA must match TensorFlow’s requirements. The pip package tensorflow[and-cuda] handles this, but if you install manually, check the official docs.

Tips

Use a dedicated environment per project – This prevents dependency clashes between different projects.
Keep TensorFlow updated – Run pip install --upgrade tensorflow periodically to get bug fixes and performance improvements.
Check GPU support early – If you have an NVIDIA GPU, verify it’s detected before installing the GPU version. Run nvidia-smi to see driver and GPU info.
Set environment variables for performance – For CPU, you can set export TF_NUM_INTRAOP_THREADS=4 (adjust as needed) to control thread usage.
Use a requirements.txt file – For reproducibility, list your packages and versions in a file and install with pip install -r requirements.txt.

Troubleshooting

ModuleNotFoundError: No module named ‘tensorflow’ – This usually means the environment isn’t activated or pip installed to a different Python. Run which python to confirm you’re in the virtual environment, then reinstall.

ImportError: libcublas.so.11: cannot open shared object file – This is a CUDA library issue. If you used tensorflow[and-cuda], ensure your NVIDIA driver is recent. If you installed CUDA manually, check that the library paths are set correctly (e.g., export LD_LIBRARY_PATH=/usr/local/cuda/lib64).

GPU not detected – Run nvidia-smi. If it fails, install the NVIDIA driver. If it works but TensorFlow doesn’t see the GPU, check that you installed the GPU-enabled package and that your GPU is supported (compute capability 3.5+).

Out of memory during installation – pip may cache packages. Free up space with pip cache purge or use pip install --no-cache-dir tensorflow.

Permission denied when creating venv – If you get a permission error, make sure you have write permissions in the current directory. You can create the environment in your home directory.

Slow performance on CPU – TensorFlow by default uses all cores. If you see high CPU usage but slow training, try setting TF_NUM_INTRAOP_THREADS to the number of physical cores.

Frequently Asked Questions

Q: Do I need a GPU to run TensorFlow? – No, TensorFlow works on CPU, but training large models will be significantly slower. GPU acceleration is recommended for deep learning.

Q: Can I install TensorFlow on Ubuntu 18.04? – Yes, but you may need to use an older TensorFlow version (2.5 or earlier) that supports Python 3.6. It’s better to upgrade to a newer Ubuntu if possible.

Q: How do I uninstall TensorFlow? – Activate the environment and run pip uninstall tensorflow. To remove the environment entirely, just delete the tf-env folder.

Q: What is the difference between tensorflow and tensorflow-cpu? – The tensorflow package includes both CPU and GPU support (with the right CUDA libraries). tensorflow-cpu is a smaller CPU-only build. For most users, tensorflow is fine.

Q: Why does pip install take so long? – TensorFlow is a large package (~500 MB). The download and installation can take several minutes depending on your internet speed. Ensure you have a stable connection.

Q: Can I use TensorFlow with PyPy or other Python implementations? – No, TensorFlow only supports CPython. Stick with the standard Python 3.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →