Creating 3d Environments

[Browning Winters]

Usedto contain a specific Python interpreter and software libraries andbinaries which are needed to support a project (library or application). Theseare by default isolated from software in other virtual environments and Pythoninterpreters and libraries installed in the operating system.

While symlinks are supported on Windows, they are not recommended. Ofparticular note is that double-clicking python.exe in File Explorerwill resolve the symlink eagerly and ignore the virtual environment.

When a Python interpreter is running from a virtual environment,sys.prefix and sys.exec_prefixpoint to the directories of the virtual environment,whereas sys.base_prefix and sys.base_exec_prefixpoint to those of the base Python used to create the environment.It is sufficient to checksys.prefix != sys.base_prefix to determine if the current interpreter isrunning from a virtual environment.

When a virtual environment has been activated, the VIRTUAL_ENVenvironment variable is set to the path of the environment.Since explicitly activating a virtual environment is not required to use it,VIRTUAL_ENV cannot be relied upon to determinewhether a virtual environment is being used.

You can deactivate a virtual environment by typing deactivate in your shell.The exact mechanism is platform-specific and is an internal implementationdetail (typically, a script or shell function will be used).

The high-level method described above makes use of a simple API which providesmechanisms for third-party virtual environment creators to customize environmentcreation according to their needs, the EnvBuilder class.

Create a virtual environment by specifying the target directory(absolute or relative to the current directory) which is to contain thevirtual environment. The create method will either create theenvironment in the specified directory, or raise an appropriateexception.

Creates a copy or symlink to the Python executable in the environment.On POSIX systems, if a specific executable python3.x was used,symlinks to python and python3 will be created pointing to thatexecutable, unless files with those names already exist.

Changed in version 3.7.2: Windows now uses redirector scripts for python[w].exe instead ofcopying the actual binaries. In 3.7.2 only setup_python() doesnothing unless running from a build in the source tree.

Changed in version 3.7.3: Windows copies the redirector scripts as part of setup_python()instead of setup_scripts(). This was not the case in 3.7.2.When using symlinks, the original executables will be linked.

With conda, you can create, export, list, remove, and updateenvironments that have different versions of Python and/orpackages installed in them. Switching or moving betweenenvironments is called activating the environment. You can alsoshare an environment file.

To automatically install pip or another program every time a newenvironment is created, add the default programs to thecreate_default_packages sectionof your .condarc configuration file. The default packages areinstalled every time you create a new environment. If you do notwant the default packages installed in a particular environment,use the --no-default-packages flag:

You can control where a conda environment lives by providing a pathto a target directory when creating the environment. For example,the following command will create a new environment in a subdirectoryof the current working directory called envs:

An explicit spec file is not usually cross platform, andtherefore has a comment at the top such as # platform: osx-64showing the platform where it was created. This platform is theone where this spec file is known to work. On other platforms,the packages specified might not be available or dependenciesmight be missing for some of the key packages already in thespec.

Conda does not check architecture or dependencies when installingfrom a spec file. To ensure that the packages work correctly,make sure that the file was created from a working environment,and use it on the same architecture, operating system, andplatform, such as linux-64 or osx-64.

Activating environments is essential to making the software in the environmentswork well. Activation entails two primary functions: adding entries to PATH forthe environment and running any activation scripts that the environment maycontain. These activation scripts are how packages can set arbitraryenvironment variables that may be necessary for their operation. You can alsouse the config API to set environment variables.

On Windows, PATH is composed of two parts, the system PATH and theuser PATH. The system PATH always comes first. When you installAnaconda for "Just Me", we add it to the user PATH. When you installfor "All Users", we add it to the system PATH. In the former case,you can end up with system PATH values taking precedence overyour entries. In the latter case, you do not. We do not recommendmulti-user installs.

Windows is extremely sensitive to proper activation. This is becausethe Windows library loader does not support the concept of librariesand executables that know where to search for their dependencies(RPATH). Instead, Windows relies on a dynamic-link library search order.

If environments are not active, libraries won't be found and therewill be lots of errors. HTTP or SSL errors are common errors when thePython in a child environment can't find the necessary OpenSSL library.

Conda itself includes some special workarounds to add its necessary PATHentries. This makes it so that it can be called without activation orwith any child environment active. In general, calling any executable inan environment without first activating that environment will likely not work.For the ability to run executables in activated environments, you may beinterested in the conda run command.

Earlier versions of conda introduced scripts to make activationbehavior uniform across operating systems. Conda 4.4 allowedconda activate myenv. Conda 4.6 added extensive initializationsupport so that conda works faster and less disruptively ona wide variety of shells (bash, zsh, csh, fish, xonsh, and more).Now these shells can use the conda activate command.Removing the need to modify PATH makes conda less disruptive toother software on your system. For more information, read theoutput from conda init --help.

This setting controls whether or not conda activates your baseenvironment when it first starts up. You'll have the condacommand available either way, but without activating the environment,none of the other programs in the environment will be available untilthe environment is activated with conda activate base. Peoplesometimes choose this setting to speed up the time their shell takesto start up or to keep conda-installed software from automaticallyhiding their other software.

By default, conda activate will deactivate the current environmentbefore activating the new environment and reactivate it whendeactivating the new environment. Sometimes you may want to leavethe current environment PATH entries in place so that you can continueto easily access command-line programs from the first environment.This is most commonly encountered when common command-line utilitiesare installed in the base environment. To retain the current environmentin the PATH, you can activate the new environment using:

To simply return to the base environment, it's better to call condaactivate with no environment specified, rather than to try to deactivate. Ifyou run conda deactivate from your base environment, you may lose theability to run conda at all. Don't worry, that's local to this shell - you canstart a new one. However, if the environment was activated using --stack(or was automatically stacked) then it is better to use conda deactivate.

Issues may arise when using pip and conda together. When combining conda and pip,it is best to use an isolated conda environment. Only after conda has been used toinstall as many packages as possible should pip be used to install any remainingsoftware. If modifications are needed to the environment, it is best to create anew environment rather than running conda after pip. When appropriate, conda andpip requirements should be stored in text files.

If you want to associate environment variables with an environment,you can use the config API. This is recommended as an alternative tousing activate and deactivate scripts since those are an execution ofarbitrary code that may not be safe.

Suppose you want an environment "analytics" to store both asecret key needed to log in to a server and a path to aconfiguration file. The sections below explain how to write ascript named env_vars to do this on Windows and macOS or Linux.

You can name these scripts anything you like. However, multiplepackages may create script files, so be sure to use descriptivenames that are not used by other packages. One popular option isto give the script a name in the formpackagename-scriptname.sh, or on Windows,packagename-scriptname.bat.

You may want to share your environment with someone else---forexample, so they can re-create a test that you have done. Toallow them to quickly reproduce your environment, with all of itspackages and versions, give them a copy of yourenvironment.yml file.

Note the use of the wildcard * when defining a few of theversions in the complex environment file. Keeping the major andminor versions fixed while allowing the patch to be any numberallows you to use your environment file to get any bug fixeswhile still maintaining consistency in your environment. Formore information on package installation values,see Package search and install specifications.

Adding nodefaults to the channels list in environment.ymlis similar to removing defaults from the channelslist in the .condarc file. However,changing environment.yml affects only one of your condaenvironments while changing .condarc affects them all.

Conda keeps a history of all the changes made to your environment,so you can easily "roll back" to a previous version. To list the history of each change to the current environment:conda list --revisions

3a8082e126