Skip to contents

Remove a Conda environment

Source: R/remove_env.R
remove_env.Rd

Removes an environment managed by condathis.

Usage

remove_env(
  env_name = "condathis-env",
  method = "auto",
  verbose = c("output", "silent", "cmd", "spinner", "full")
)

Arguments

env_name

Character string with the environment name. It must be a plain directory name that is valid on Linux, macOS and Windows:

  • Not empty, and not . or ...

  • Not starting with -, and not ending with ..

  • Without path separators, :, #, whitespace, control characters or <>"|?*.

  • Not a Windows device name, such as NUL or COM1 (see Environment names in create_env()).

Invalid values abort with class condathis_invalid_env_name. Functions that take only names reject an env_path() value with class condathis_env_path_read_only. run(), run_bin(), run_pipeline() and run_step() accept one.

method

Character string naming the backend. "auto" (the default) uses the backend that owns env_name when it exists, and otherwise the first available backend in getOption("condathis.backend_priority") order (see condathis-options). Any name from list_registered_backend_names() selects that backend, and "micromamba" is built in. The name of a backend whose package condathis knows, such as "rattler" of the rattlerthis package, also selects it. condathis loads the package on first use. It aborts with class condathis_backend_not_installed when the package is not installed. "native" is a deprecated alias for "micromamba" (warns once per session). If you name a backend other than the owner, functions that change the environment abort with class condathis_backend_mismatch. The others warn (condathis_backend_mismatch_warning) and use the owner. An environment found under several backends aborts with condathis_backend_ambiguous_env unless method names one of them. Invalid values abort with class condathis_invalid_method.

verbose

Character string that controls the console output. One of:

  • "output": show the output of the command and the messages of condathis.

  • "silent": show nothing.

  • "cmd": show the command line.

  • "spinner": show only a spinner.

  • "full": show the command line, the output, and the backend's own log.

TRUE means "output" and FALSE means "silent". Every level except "silent" shows a spinner in interactive sessions. Invalid values abort with class condathis_invalid_verbose (see condathis-conditions). The default is shown in Usage.

The command line shown, the cmd of a result and the messages of condathis show the password and the token of a URL as *****. micromamba does the same (https://user:*****@host/channel, https://host/t/*****/channel). The command still gets them.

Value

A condathis_result object, invisibly: a classed list with status, stdout, stderr, timeout, pid, cmd and env_name. cmd is the command line that the backend ran, or NA when the backend reports none. stdout, stderr and pid are NA when the backend reports none, and pid always is with micromamba. An environment that does not exist aborts with class condathis_remove_env_env_not_found (also condathis_env_not_found and the 0.1.4 class condathis_error_env_remove). remove_env() deletes nothing then, not even a leftover directory of that name. A backend failure aborts with class condathis_remove_env_failed (also condathis_backend_error), with the backend's error as the parent. micromamba runs the pre-unlink scripts of packages before it removes them. A backend that does not makes remove_env() warn with class condathis_remove_env_link_scripts_skipped (also condathis_link_scripts_skipped). The warning names the packages.

Details

With the micromamba backend, remove_env() does not change ~/.conda/environments.txt, the registry that conda and mamba share. A line that create_env() added to that file stays (see Details in get_install_dir()). On Windows, it also leaves the Start Menu shortcuts that condathis 0.1.4 and earlier added for packages such as spyder. Delete them from the Start Menu.

Other R sessions

Only one R session at a time changes an environment. create_env(), install_packages() and remove_env() hold a lock on the environment name while they work, with every backend. A call for an environment that another R session is changing waits until that session is done. After two seconds, the call says so with a message of class condathis_env_lock_waiting. verbose = "silent" hides this message. Ctrl-C stops the wait. clean_cache() waits until no other R session creates an environment or installs packages. Those calls wait while it cleans. Each wait gives a message of class condathis_cache_lock_waiting. A lock lasts only as long as its session, also when the session crashes or is killed. The lock files are in the directory locks of the condathis data directory (see get_install_dir()). Where files cannot be locked, such as on some network file systems, the call goes on without the lock. When it changes something, it warns once per session with class condathis_env_lock_unavailable.

See also

condathis-conditions for every condition class.

Other environments: create_env(), env_exists(), env_path(), get_env_dir(), install_packages(), list_envs(), list_packages(), validate_env()

Examples

if (FALSE) { # \dontrun{
condathis::with_sandbox_dir({
  # A local channel shipped with condathis, with `polyglot`: a
  # dependency-free script that runs on Linux, macOS and Windows.
  channel <- system.file(
    "extdata", "polyglot-channel",
    package = "condathis"
  )
  condathis::create_env(
    "polyglot",
    env_name = "polyglot-env",
    channels = channel
  )
  condathis::remove_env(env_name = "polyglot-env")
})
} # }