Merge pull request conda#9425 from rrigdon/activating-Windows-env

Added two topics to troubleshooting, clarified activation doc

docs/source/user-guide/tasks/manage-environments.rst

@@ -337,18 +337,50 @@ the environment, and running any activation scripts that the environment may
 contain. These activation scripts are how packages can set arbitrary
 environment variables that may be necessary for their operation.
 
+When `installing Anaconda <http://docs.continuum.io/anaconda/install.html>`_,
+you have the option to “Add Anaconda
+to my PATH environment variable.” This is not recommended because the
+add to PATH option appends Anaconda to PATH. When the installer appends
+to PATH, it does not call the activation scripts.
+
+On Windows, PATH is composed of two parts, the system PATH and the
+user PATH. The system PATH always comes first. When you install
+Anaconda for Just Me, we add it to the user PATH. When you install
+for All Users, we add it to the system PATH. In the former case,
+you can end up with system PATH values taking precedence over
+our entries. In the latter case, you do not. We do not recommend
+All Users installs.
+
+Activation prepends to PATH. This only takes effect
+when you have the environment active so it is local to a terminal session,
+not global.
+
 To activate an environment: ``conda activate myenv``
 
 .. note::
    Replace ``myenv`` with the environment name or directory path.
 
 Conda prepends the path name ``myenv`` onto your system command.
 
+You may receive a warning message if you have not activated your environment:
+
+.. code-block:: Python
+
+   Warning:
+   This Python interpreter is in a conda environment, but the environment has
+   not been activated. Libraries may fail to load. To activate this environment
+   please see https://conda.io/activation.
+
+If you receive this warning, you need to activate your environment. To do
+so on Windows, run: ``c:\Anaconda3\Scripts\activate base`` in
+Anaconda Prompt.
+
 Windows is extremely sensitive to proper activation. This is because
 the Windows library loader does not support the concept of libraries
 and executables that know where to search for their dependencies
 (RPATH). Instead, Windows relies on a `dynamic-link library search order <https://docs.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order>`_.
-If environments are not active, libraries won't get found and there
+
+If environments are not active, libraries won't be found and there
 will be lots of errors. HTTP or SSL errors are common errors when the
 Python in a child environment can't find the necessary OpenSSL library.
 
@@ -359,6 +391,8 @@ an environment without first activating that environment will likely not work.
 For the ability to run executables in activated environments, you may be
 interested in the ``conda run`` command.
 
+If you experience errors with PATH, review our :ref:`troubleshooting <path-error>`.
+
 Conda init
 ----------
 

docs/source/user-guide/troubleshooting.rst

@@ -1,13 +1,13 @@
-=================
+===============
 Troubleshooting
-=================
+===============
 
 .. contents::
    :local:
    :depth: 1
 
 
-Using Conda in Windows Batch script exits early
+Using conda in Windows Batch script exits early
 ===============================================
 
 In conda 4.6+, the way that you interact with conda goes through a batch script (``%PREFIX%\condabin\conda.bat``).
@@ -226,7 +226,7 @@ Conda has three similar options.
 
        # # ssl_verify (bool, str)
        # #   aliases: verify_ssl
-       # #   Conda verifies SSL certificates for HTTPS requests, just like a web
+       # #   conda verifies SSL certificates for HTTPS requests, just like a web
        # #   browser. By default, SSL verification is enabled and conda operations
        # #   will fail if a required URL's certificate cannot be verified. Setting
        # #   ssl_verify to False disables certification verification. The value for
@@ -253,7 +253,7 @@ Conda has three similar options.
 
        # # ssl_verify (bool, str)
        # #   aliases: verify_ssl
-       # #   Conda verifies SSL certificates for HTTPS requests, just like a web
+       # #   conda verifies SSL certificates for HTTPS requests, just like a web
        # #   browser. By default, SSL verification is enabled, and conda operations
        # #   will fail if a required URL's certificate cannot be verified. Setting
        # #   ssl_verify to False disables certification verification. The value for
@@ -928,7 +928,7 @@ Now you have a software environment sandbox created with Python
 .. _auto-upgrade:
 
 Conda automatically upgrades to unwanted version
-===================================================
+================================================
 
 When making a Python package for an app, you create an
 environment for the app from a file ``req.txt`` that sets a
@@ -978,7 +978,7 @@ EXAMPLE: If my conda info says package cache : /opt/conda/pkgs and my Python ver
 
 
 ValidationError: Invalid value for timestamp
-=============================================
+============================================
 
 Cause
 ------
@@ -1007,3 +1007,88 @@ Solution
 --------
 
 Remove all non-ASCII from PATH or switch to Python 3.
+
+
+Windows environment has not been activated
+==========================================
+
+Cause
+-----
+You may receive a warning message if you have not activated your environment:
+
+.. code-block:: Python
+
+   Warning:
+   This Python interpreter is in a conda environment, but the environment has
+   not been activated. Libraries may fail to load. To activate this environment
+   please see https://conda.io/activation
+
+Solution
+--------
+
+If you receive this warning, you need to activate your environment.
+To do so on Windows, use the Anaconda Prompt shortcut in your Windows
+start menu. If you have an existing cmd.exe session that you’d like to
+activate conda in, run:
+``call <your anaconda/miniconda install location>\Scripts\activate base``.
+
+
+.. _path-error:
+
+The system cannot find the path specified on Windows
+====================================================
+
+Cause
+-----
+PATH does not contain entries for all of the necessary conda directories.
+PATH may have too many entries from 3rd party software adding itself to
+PATH at install time, despite the user not needing to run the software via PATH lookup.
+
+Solution
+--------
+
+Strip PATH to have fewer entries and activate your environment.
+
+If there's some software that needs to be found on PATH (you run it via
+the CLI), we recommend that you create your own batch files to set PATH
+dynamically within a console session, rather than permanently modifying
+PATH in the system settings.
+
+For example, a new conda prompt batch file that first strips PATH, then
+calls the correct activation procedure could look like:
+
+.. code-block:: Python
+
+   set
+   PATH=”%SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem;%SYSTEMROOT%\System32\WindowsPowerShell\v1.0\;<3rd-party-entries>”
+   call “<miniconda/anaconda root>\Scripts\activate”
+
+If you need to run 3rd party software (software other than Windows
+built-ins and Anaconda) from this custom conda prompt, then you should add
+those entries (and only those strictly necessary) to the set PATH entry
+above. Note that only the quotes wrapping the entire expression should be
+there. That is how variables are properly set in batch scripts, and these
+account for any spaces in any entries in PATH. No additional quotes should
+be within the value assigned to PATH.
+ 
+To make 3rd party software take precedence over the same-named programs
+as supplied by conda, add it to PATH after activating conda:
+
+.. code-block:: Python
+   
+   set
+   “PATH=%SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem;%SYSTEMROOT%\System32\WindowsPowerShell\v1.0\”
+   call “<miniconda/anaconda root>\Scripts\activate”
+   set “PATH=<3rd-party-entries>;%PATH%”
+
+
+To make conda software take precedence, call the activation script last.
+Because activation prepends the conda environment PATH entries,
+they have priority.
+
+.. code-block:: Python
+
+   set
+   PATH=”%SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem;%SYSTEMROOT%\System32\WindowsPowerShell\v1.0\;<3rd-party-entries>”
+   call “<miniconda/anaconda root>\Scripts\activate”
+