install_tensorflow: Install TensorFlow and its dependencies

In tensorflow: R Interface to 'TensorFlow'

Install TensorFlow and its dependencies

Description

This function installs TensorFlow into a persistant virtual environment. Beginning with reticulate version 1.41, in most circumstances, creating a persistent virtual environment by calling the install_tensorflow() function is no longer necessary, because reticulate automatically will resolve a python environment that satisfies all python requirements declared with reticulate::py_require().

New code is recommended to call py_require_tensorflow() at the start of an R session to declare tensorflow requirements via py_requore(). In a future package update this will by default be done in tensorflow's .onLoad hook.

The py_require_tensorflow() function that can dynamically modify the python requirements to enable usage of a GPU if one is available and usable by the R session.

The Python packages registered with py_require() by py_require_tensorflow():

• On Linux: if a GPU is detected: "tensorflow[and-cuda]", otherwise, "tensorflow-cpu".

• On macOS: "tensorflow" is declared. The default package is not capable of using the GPU. To enable TensorFlow usage of the GPU, call reticulate::py_require("tensorflow-metal") before reticulate has initialized Python. Note that not all features of TensorFlow work correctly if tensorflow-metal is installed. There are known issues with random number generators like tf$random$stateless_uniform(), likely others as well.

• On Windows: "tensorflow" and "numpy<2" are declared. Note that TensorFlow GPU usage on Windows is no longer supported (Since TensorFlow 2.10). To use a GPU on windows, use TensorFlow via WSL. "numpy<2" is declared because at the time of this publishing, the pre-built binaries of tensorflow for Windows are not compatible with numpy>2.

install_tensorflow() creates a new virtual environment containing the tensorflow python package and it's direct dependencies. For creating a virtual environment with more complete set packages that includes additional optional dependencies, use keras3::install_keras().

Usage

install_tensorflow(
  method = c("auto", "virtualenv", "conda"),
  conda = "auto",
  version = "default",
  envname = "r-tensorflow",
  extra_packages = NULL,
  restart_session = TRUE,
  conda_python_version = NULL,
  ...,
  cuda = NULL,
  metal = FALSE,
  pip_ignore_installed = FALSE,
  new_env = identical(envname, "r-tensorflow"),
  python_version = NULL
)

py_require_tensorflow(use_gpu = NA)

Arguments

method	Installation method. By default, "auto" automatically finds a method that will work in the local environment. Change the default to force a specific installation method. Note that the "virtualenv" method is not available on Windows.
conda	The path to a conda executable. Use "auto" to allow reticulate to automatically find an appropriate conda binary. See Finding Conda and conda_binary() for more details.
version	TensorFlow version to install. Valid values include: "default" installs 2.20 "release" installs the latest release version of tensorflow (which may be incompatible with the current version of the R package) A version specification like "2.4" or "2.4.0". Note that if the patch version is not supplied, the latest patch release is installed (e.g., "2.4" today installs version "2.4.2") nightly for the latest available nightly build. To any specification, you can append "-cpu" to install the cpu version only of the package (e.g., "2.4-cpu") The full URL or path to a installer binary or python *.whl file.
envname	The name, or full path, of the environment in which Python packages are to be installed. When NULL (the default), the active environment as set by the RETICULATE_PYTHON_ENV variable will be used; if that is unset, then the r-reticulate environment will be used.
extra_packages	Additional Python packages to install along with TensorFlow.
restart_session	Restart R session after installing (note this will only occur within RStudio).
conda_python_version	Passed to conda (only applicable if method = "conda")
...	other arguments passed to reticulate::conda_install() or reticulate::virtualenv_install(), depending on the method used.
cuda	logical TRUE or FALSE. If install_tensorflow() detects the platform is Linux, an Nvidia GPU is available, and the TensorFlow version is 2.14 (the default), it will install also install the required CUDA libraries through pip.
metal	Whether to install tensorflow-metal pip package on Arm Macs. This enables tensorflow to use the GPU. Pass a string to install a specific version like ⁠"tensorflow-metal==0.7.*⁠.
pip_ignore_installed	Whether pip should ignore installed python packages and reinstall all already installed python packages.
new_env	If TRUE, any existing Python virtual environment and/or conda environment specified by envname is deleted first.
python_version	Select the Python that will be used to create the virtualenv. Pass a string with version constraints like "3.8", or ">=3.9,<=3.11" or a file path to a python executable like "/path/to/bin/python3". The supplied value is passed on to reticulate::virtualenv_starter(). Note that the Python version must be compatible with the requested TensorFlow version, documented here: https://www.tensorflow.org/install/pip#system-requirements
use_gpu	Only consulted if on Linux. It has no effect on macOS or Windows. If NA, the R package will attempt to detect a GPU. If a GPU is detected, then this is taken as TRUE, FALSE otherwise. If TRUE, then tensorflow[and-cuda] is declared, otherwise, tensorflow-cpu is declared via py_require().

Custom Installation

install_tensorflow() or keras3::install_keras() isn't required to use tensorflow with the package. If you manually configure a python environment with the required dependencies, you can tell R to use it by pointing reticulate at it, commonly by setting an environment variable:

Sys.setenv("RETICULATE_PYTHON" = "~/path/to/python-env/bin/python")

Apple Silicon

Beginning with Tensorflow version 2.13, the default tensorflow package now works on Apple Silicon. See https://developer.apple.com/metal/tensorflow-plugin/ for instructions on how to install older versions of Tensorflow on macOS. Please note that not all operations are supported on Arm Mac GPUs. You can work around the missing operations by pinning operations to CPU. For example:

x <- array(runif(64*64), c(1, 64, 64))
keras3::layer_random_rotation(x, .5)  # Error:
# No registered 'RngReadAndSkip' OpKernel for 'GPU' devices
# Pin the operation to the CPU to avoid the error
with(tf$device("CPU"), keras3::layer_random_rotation(x, .5) ) # No Error

Additional Packages

If you wish to add additional PyPI packages to your Keras / TensorFlow environment you can either specify the packages in the extra_packages argument of install_tensorflow() or install_keras(), or alternatively install them into an existing environment using the reticulate::py_install() function. Note that install_keras() includes a set of additional python packages by default, see ?keras3::install_keras for details.

See Also

• keras3::install_keras()

• https://tensorflow.rstudio.com/reference/tensorflow/install_tensorflow

tensorflow documentation built on Aug. 22, 2025, 5:12 p.m.