From da2d74c045347e4775d0aef08c9f29d20f4a348b Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Fri, 8 May 2026 09:10:00 -0400 Subject: [PATCH] Document py_require_tensorflow install path --- R/install.R | 41 +++++++++++++++++++++++------------- README.md | 26 ++++++++++++++++++----- man/install_tensorflow.Rd | 44 ++++++++++++++++++++++++--------------- 3 files changed, 74 insertions(+), 37 deletions(-) diff --git a/R/install.R b/R/install.R index ff85bba..cd41016 100644 --- a/R/install.R +++ b/R/install.R @@ -1,19 +1,29 @@ -#' Install TensorFlow and its dependencies +#' Declare TensorFlow requirements or install TensorFlow #' #' @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()`. +#' `py_require_tensorflow()` declares the Python packages needed to use +#' TensorFlow with this package. Call it near the start of an R session, before +#' reticulate initializes Python: #' -#' 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. +#' ```r +#' library(tensorflow) +#' py_require_tensorflow() +#' ``` #' -#' The `py_require_tensorflow()` function that can dynamically modify the python +#' Beginning with reticulate version 1.41, reticulate can automatically resolve a +#' Python environment that satisfies all Python requirements declared with +#' `reticulate::py_require()`. Reticulate will take care of the details: it will +#' choose or create a suitable Python environment, install TensorFlow and its +#' Python dependencies, and make that environment available to this package. You +#' do not need to install Python packages or configure a Python environment +#' manually. +#' +#' In most circumstances, creating a persistent virtual environment by calling +#' `install_tensorflow()` is no longer necessary. In a future package update +#' this will by default be done in tensorflow's `.onLoad` hook. +#' +#' The `py_require_tensorflow()` function can dynamically modify the Python #' requirements to enable usage of a GPU if one is available and usable by the R #' session. #' @@ -36,10 +46,11 @@ #' 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()`]. +#' `install_tensorflow()` remains available for users who want to explicitly +#' create a persistent virtual environment. It creates a new virtual environment +#' containing the `tensorflow` Python package and its direct dependencies. For +#' creating a virtual environment with a more complete set of packages that +#' includes additional optional dependencies, use [`keras3::install_keras()`]. #' #' @section Custom Installation: `install_tensorflow()` or #' `keras3::install_keras()` isn't required to use tensorflow with the diff --git a/README.md b/README.md index 3b96012..7203b60 100644 --- a/README.md +++ b/README.md @@ -14,21 +14,38 @@ To get started, install the tensorflow R package from GitHub as follows: devtools::install_github("rstudio/tensorflow") ``` -Then, use the `install_tensorflow()` function to install TensorFlow: +Then, call `py_require_tensorflow()` at the start of each R session, before +using TensorFlow: ```r library(tensorflow) -install_tensorflow() +py_require_tensorflow() ``` -You can confirm that the installation succeeded with: +You can confirm that TensorFlow is available with: ```r hello <- tf$constant("Hello") print(hello) ``` -This will provide you with a default installation of TensorFlow suitable for getting started with the tensorflow R package. See the [article on installation](https://tensorflow.rstudio.com/install/) to learn about more advanced options, including installing a version of TensorFlow that takes advantage of Nvidia GPUs if you have the correct CUDA libraries installed. +This is all you need for the default setup. Reticulate will take care of the +details: it will choose or create a suitable Python environment, install +TensorFlow and its Python dependencies, and make that environment available to +the tensorflow R package. You do not need to install Python packages or +configure a Python environment manually. + +In most cases, you no longer need to call `install_tensorflow()`. If you want to +create a persistent virtual environment explicitly, use: + +```r +install_tensorflow() +``` + +See the [article on installation](https://tensorflow.rstudio.com/install/) to +learn about more advanced options, including installing a version of TensorFlow +that takes advantage of Nvidia GPUs if you have the correct CUDA libraries +installed. ## Documentation @@ -40,4 +57,3 @@ The tensorflow package provides code completion and inline help for the TensorFl - diff --git a/man/install_tensorflow.Rd b/man/install_tensorflow.Rd index 52df6b6..cac9be3 100644 --- a/man/install_tensorflow.Rd +++ b/man/install_tensorflow.Rd @@ -3,7 +3,7 @@ \name{install_tensorflow} \alias{install_tensorflow} \alias{py_require_tensorflow} -\title{Install TensorFlow and its dependencies} +\title{Declare TensorFlow requirements or install TensorFlow} \usage{ install_tensorflow( method = c("auto", "virtualenv", "conda"), @@ -93,18 +93,27 @@ detected, then this is taken as \code{TRUE}, \code{FALSE} otherwise. If \code{TR via \code{py_require()}.} } \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 \code{install_tensorflow()} function -is no longer necessary, because reticulate automatically will resolve a -python environment that satisfies all python requirements declared with -\code{reticulate::py_require()}. - -New code is recommended to call \code{py_require_tensorflow()} at the start of an -R session to declare tensorflow requirements via \code{py_requore()}. In a future -package update this will by default be done in tensorflow's \code{.onLoad} hook. - -The \code{py_require_tensorflow()} function that can dynamically modify the python +\code{py_require_tensorflow()} declares the Python packages needed to use +TensorFlow with this package. Call it near the start of an R session, before +reticulate initializes Python: + +\if{html}{\out{
}}\preformatted{library(tensorflow) +py_require_tensorflow() +}\if{html}{\out{
}} + +Beginning with reticulate version 1.41, reticulate can automatically resolve a +Python environment that satisfies all Python requirements declared with +\code{reticulate::py_require()}. Reticulate will take care of the details: it will +choose or create a suitable Python environment, install TensorFlow and its +Python dependencies, and make that environment available to this package. You +do not need to install Python packages or configure a Python environment +manually. + +In most circumstances, creating a persistent virtual environment by calling +\code{install_tensorflow()} is no longer necessary. In a future package update +this will by default be done in tensorflow's \code{.onLoad} hook. + +The \code{py_require_tensorflow()} function can dynamically modify the Python requirements to enable usage of a GPU if one is available and usable by the R session. @@ -126,10 +135,11 @@ declared because at the time of this publishing, the pre-built binaries of \code{tensorflow} for Windows are not compatible with \code{numpy>2}. } -\code{install_tensorflow()} creates a new virtual environment containing the -\code{tensorflow} python package and it's direct dependencies. For creating a -virtual environment with more complete set packages that includes additional -optional dependencies, use \code{\link[keras3:install_keras]{keras3::install_keras()}}. +\code{install_tensorflow()} remains available for users who want to explicitly +create a persistent virtual environment. It creates a new virtual environment +containing the \code{tensorflow} Python package and its direct dependencies. For +creating a virtual environment with a more complete set of packages that +includes additional optional dependencies, use \code{\link[keras3:install_keras]{keras3::install_keras()}}. } \section{Custom Installation}{ \code{install_tensorflow()} or