renviron
is an R package designed to streamline the management of
environment variables within R projects. It facilitates the creation,
modification, and deletion of variables in the .Renviron
file,
enabling dynamic environment variable handling directly from R. This
toolkit is essential for projects that require precise control over
environment configurations, such as managing API keys, database
credentials, and application-specific settings.
In many instances, We found ourselves needing to programmatically manage
the .Renviron
file. And you know, if you have to do it twice, try to
automate it. While there are libraries in R that allow loading
environment variables from .Renviron
files or even .env
files,
renviron
does not limit itself to just loading these variables. It
also allows for the creation, modification, and deletion of environment
variables directly from R.
This comprehensive approach to environment variable management makes renviron an invaluable tool for R users who need to dynamically adjust their setup according to different project needs or security guidelines. Whether you’re setting up a new project, integrating with other software, or simply organizing your work environment, renviron provides a robust, flexible toolkit to manage your environment variables effectively and securely.
You can install the development version of renviron
from Adatar’s
r-universe with:
install.packages("renviron", repos = c("https://adatar-do.r-universe.dev", "https://cloud.r-project.org"))
When working in RStudio, the project-level .Renviron
file is
automatically loaded upon opening a project, making environment
variables defined at the project scope readily available. However,
renviron
extends this functionality by allowing management of
environment variables across both project and user scopes:
- Project Scope: Variables specific to the current R project.
- User Scope: Global variables that apply across all projects for the user.
This distinction is crucial for managing environment variables that are either specific to a project or meant to be globally accessible across multiple projects.
The scope
argument is a powerful feature in the renviron
package
that provides flexibility in managing environment variables across
different levels of your R environment. Available in all main functions
of the package, scope
allows you to specify whether you want to
interact with environment variables at the project level, the user
level, or both. This feature is especially useful when working within
RStudio, which automatically loads project-level .Renviron
files.
-
Project Scope: When
scope
is set to"project"
,renviron
functions will operate on the.Renviron
file located in your current R project directory. This is useful for setting environment variables that are specific to the project you are working on. -
User Scope: Setting
scope
to"user"
directsrenviron
functions to work with the.Renviron
file in your user home directory. Variables set at this level are accessible across all your R projects, making this scope suitable for global configurations and secrets. -
Both Scopes: You can also specify both scopes by using
scope = c("user", "project")
. In this case,renviron
functions will prioritize the project scope over the user scope when reading, adding, or updating environment variables. This ensures that project-specific settings take precedence, while still allowing access to user-level configurations.
All main functions in the renviron
package, including renviron_load
,
renviron_list
, renviron_add
, renviron_get
, and renviron_delete
,
support the scope
argument. This consistency allows you to seamlessly
manage your environment variables with precision, whether you’re loading
variables, adding new ones, retrieving specific variables, or deleting
them.
For example, RStudio will automatically load the project-level
.Renviron
file when you open a project. To load environment variables
from user scope, you can use:
renviron_load("user")
Now you can access both, the project-level and the user-level variables in your R environment.
To add a new variable to the user-level .Renviron
file, bypassing the
project-level file, you can specify:
renviron_add("GLOBAL_API_KEY", "12345abcde", scope = "user")
This uniform approach to scope
across the renviron
package enhances
your control over where and how environment variables are managed within
your R environment, catering to a wide range of use cases from
project-specific configurations to global settings.
Load all environment variables from the .Renviron
file.
library(renviron)
renviron_load()
#> ✔ Setting active project to 'C:/Users/drdsd/Documents/Projects/renviron'
Now you can access the variables from the system environment
Sys.getenv("SECRET_1")
#> [1] "123abc"
Alternatively, you can capture the variables directly into a named list
env <- renviron_load()
env$SECRET_1
#> [1] "123abc"
You can also load other env files by specifying its name
renviron_load(.file = ".env")
Additionally, you can specify what variables to load by passing a vector of names
renviron_load(.vars = c("DATAFARO_TOKEN", "API_KEY"))
You can also unset all environment variables loaded from the .Renviron
file.
# Unset all environment variables loaded from .Renviron
renviron_unset_all()
Before you modify or delete an environment variable, it might be
necessary to check if it actually exists in the scope you are working
with. The renviron_exists
function provides a straightforward way to
do this:
exists <- renviron_exists("API_KEY")
if (exists) {
print("API_KEY exists in the .Renviron file.")
} else {
print("API_KEY does not exist.")
}
#> [1] "API_KEY does not exist."
This function can be particularly useful when scripting or when working with conditional logic based on the presence of certain variables.
Get a list of all environment variables currently set. This will return a named list with all the variables and their values. For security reasons, the values are masked. So, you can use this function to list all the variables without revealing their values.
renviron_list()
#> SECRET_1 GITHUB_TOKEN DATAFARO_TOKEN NEW_VAR Hola
#> "*****" "*****" "*****" "*****" "*****"
Add a new environment variable or update an existing one.
renviron_add("NEW_VAR", "new_value")
Sys.getenv("NEW_VAR")
#> [1] "new_value"
This will add or update the variable NEW_VAR
with the value
new_value
in the system environment, if you want to save it to the
.Renviron
file, you can use the in_place
argument.
renviron_add("NEW_VAR", "new_value", in_place = TRUE, confirm = FALSE)
renviron_list()
#> SECRET_1 GITHUB_TOKEN DATAFARO_TOKEN NEW_VAR Hola
#> "*****" "*****" "*****" "*****" "*****"
Note: The confirm
argument is set to TRUE
by default, which will
prompt you to confirm the changes before saving them to the .Renviron
file. If you want to save the changes without confirmation, you can set
confirm = FALSE
.
Alternatively, you can capture the variables directly into a named list
no matter if you save it to the .Renviron
file or not.
env <- renviron_add("NEW_VAR", "new_value")
env$NEW_VAR
#> [1] "new_value"
Retrieve the value of a specific environment variable.
renviron_get("SECRET_1")
#> [1] "123abc"
Remove an environment variable.
renviron_delete("SECRET_1")
Sys.getenv("SECRET_1")
#> [1] ""
Contributions to renviron
are welcome from all! Contributions can be
made in the form of feedback, bug reports, or even better - pull
requests. Please adhere to the Code of Conduct for
all interactions with the project.
renviron
is released under the MIT License. See the bundled
LICENSE file for details.
- Thanks to all
contributors
who have helped shape
renviron
. - Special thanks to Adatar for their contributions to the project.