MRG: Update installation instructions to ensure users end up with lat…

…est version of the conda-forge package (#10580) (#10581)

doc/install/advanced.rst

@@ -13,7 +13,7 @@ conda environment to include the ``nb_conda_kernels`` package; this will
 make it easier to use MNE-Python in Jupyter Notebooks launched from the
 Anaconda GUI:
 
-.. code-block:: console
+.. code-block:: bash
 
     conda install --name=base nb_conda_kernels
 
@@ -24,7 +24,7 @@ will work correctly. On macOS, certain matplotlib functions might not work as
 expected on backends other than Qt. Enabling Qt can be accomplished when
 starting IPython from a terminal:
 
-.. code-block:: console
+.. code-block:: bash
 
     ipython --matplotlib=qt
 
@@ -88,7 +88,9 @@ Installing to a headless server
 
 With `pyvista`_:
 Download the `server environment file`_ and use it to create the conda
-environment::
+environment
+
+.. code-block:: bash
 
     curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/main/server_environment.yml
     conda env create -f server_environment.yml
@@ -134,7 +136,7 @@ It is also possible to use a system-level installation of Python (version
 |min_python_version| or higher) and use ``pip`` to install MNE-Python and its
 dependencies, using the provided `requirements file`_:
 
-.. code-block:: console
+.. code-block:: bash
 
     curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/main/requirements.txt
     pip install --user -r requirements.txt
@@ -153,7 +155,7 @@ operations (e.g. FIR filtering) by roughly an order of magnitude. To use CUDA,
 first  ensure that you are running the `NVIDIA proprietary drivers`_ on your
 operating system, and then do:
 
-.. code-block:: console
+.. code-block:: bash
 
     conda install cupy
     MNE_USE_CUDA=true python -c "import mne; mne.cuda.init_cuda(verbose=True)"
@@ -166,7 +168,7 @@ is working properly. To permanently enable CUDA in MNE, you can do::
 
 You can then test MNE CUDA support by running the associated test:
 
-.. code-block:: console
+.. code-block:: bash
 
     pytest mne/tests/test_filter.py -k cuda
 
@@ -185,7 +187,7 @@ For example, on CentOS 7.5 you might be able to use an environment variable
 to force MESA to use modern OpenGL by using this before executing
 ``spyder`` or ``python``:
 
-.. code-block:: console
+.. code-block:: bash
 
     export MESA_GL_VERSION_OVERRIDE=3.3
 
@@ -195,7 +197,7 @@ better than others, such as using the ``llvmpipe`` backend rather than ``swr``.
 MESA also can have trouble with full-screen antialiasing, which you can
 disable with:
 
-.. code-block:: console
+.. code-block:: bash
 
     export MNE_3D_OPTION_ANTIALIAS=false
 
@@ -212,15 +214,15 @@ If you have CentOS 7 or newer, you can also try some `prebuilt binaries <https:/
 After downloading the files, untar them and add them to the appropriate library paths
 using the following commands:
 
-.. code-block:: console
+.. code-block:: bash
 
     tar xzvf mesa_18.3.6_centos_lib.tgz
     export LIBGL_DRIVERS_PATH="${PWD}/lib"
     export LD_LIBRARY_PATH="${PWD}/lib"
 
 To check that everything went well, type the following:
 
-.. code-block:: console
+.. code-block:: bash
 
     glxinfo | grep "OpenGL core profile version"
 
@@ -230,7 +232,7 @@ which should give::
 
 Another way to check is to type:
 
-.. code-block:: console
+.. code-block:: bash
 
     mne sys_info
 
@@ -255,7 +257,7 @@ the pyvista 3D backend and find that you can click-drag to rotate the brain,
 but cannot adjust any of the settings sliders, it is likely that your versions
 of VTK and/or QT are incompatible. This series of commands should fix it:
 
-.. code-block:: console
+.. code-block:: bash
 
     conda uninstall vtk
     pip uninstall -y pyvista

doc/install/manual_install.rst

@@ -13,50 +13,70 @@ Install via :code:`pip` or :code:`conda`
 MNE-Python requires Python version |min_python_version| or higher. If you
 need to install Python, please see :ref:`install-python`.
 
-- If you only need MNE-Python's core functionality including 2D plotting (but
-  **without 3D visualization**), install via :code:`pip`:
+Installing MNE-Python with all dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+We suggest to install MNE-Python into its own ``conda`` environment.
 
-  .. code-block:: console
+The dependency stack is large and may take a long time (several tens of
+minutes) to resolve on some systems via the default ``conda`` solver. We
+therefore highly recommend using the
+`libmamba solver <https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community>`__,
+which is **much** faster, albeit still an experimental feature.
 
-      pip install mne
+Run in your terminal:
 
-  or via :code:`conda`:
+.. code-block:: bash
 
-  .. code-block:: console
+   conda install --name=base conda-libmamba-solver
+   conda create --experimental-solver=libmamba --strict-channel-priority --channel=conda-forge --name=mne mne
 
-      conda install --channel=conda-forge mne-base
+This will create a new ``conda`` environment called ``mne`` (you can adjust
+this by passing a different name via ``--name``) and install all
+dependencies into it.
 
-- If you plan to use MNE-Python's functions that require **HDF5 I/O** (this
-  includes :func:`mne.io.read_raw_eeglab`, :meth:`mne.SourceMorph.save`, and
-  others), you should run via :code:`pip`:
+If you need to convert structural MRI scans into models
+of the scalp, inner/outer skull, and cortical surfaces, you will also need
+:doc:`FreeSurfer <freesurfer>`.
 
-  .. code-block:: console
+Installing a minimal MNE-Python with core functionality only
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you only need MNE-Python's core functionality including 2D plotting (but
+**without 3D visualization**), install via :code:`pip`:
 
-      pip install mne[hdf5]
+.. code-block:: bash
 
-  or via :code:`conda`
+   pip install mne
 
-  .. code-block:: console
+or via :code:`conda`:
 
-     conda install --channel=conda-forge mne-base h5io h5py pymatreader
+.. code-block:: bash
 
-  to install the necessary dependencies.
+   conda create --strict-channel-priority --channel=conda-forge --name=mne mne-base
 
-- If you need MNE-Python **with 3D visualization** capabilities (e.g., plotting
-  estimated source activity on a cortical surface) it is a good idea to install
-  MNE-Python into its own ``conda`` environment. To do this:
+This will create a new ``conda`` environment called ``mne`` (you can adjust
+this by passing a different name via ``--name``).
 
-  .. code-block:: console
+Installing a minimal MNE-Python with EEGLAB I/O support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you plan to use MNE-Python's functions that require **HDF5 I/O** (this
+includes :func:`mne.io.read_raw_eeglab`, :meth:`mne.SourceMorph.save`, and
+others), you should run via :code:`pip`:
 
-     conda create --name=mne --channel=conda-forge mne
-     #                   ↑↑↑                       ↑↑↑
-     #             environment name            package name
+.. code-block:: bash
 
-  This will create a new ``conda`` environment called ``mne`` and install all
-  dependencies into it. If you need to convert structural MRI scans into models
-  of the scalp, inner/outer skull, and cortical surfaces, you will also need
-  :doc:`FreeSurfer <freesurfer>`.
+   pip install mne[hdf5]
 
+or via :code:`conda`
+
+.. code-block:: bash
+
+   conda create --strict-channel-priority --channel=conda-forge --name=mne mne-base h5io h5py pymatreader
+
+This will create a new ``conda`` environment called ``mne`` (you can adjust
+this by passing a different name via ``--name``).
+
+Installing MNE-Python for other scenarios
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The :ref:`advanced_setup` page has additional
 tips and tricks for special situations (servers, notebooks, CUDA, installing
 the development version, etc). The :ref:`contributing` has additional
@@ -70,6 +90,14 @@ Most users find it convenient to write and run their code in an `Integrated
 Development Environment`_ (IDE). Some popular choices for scientific
 Python development are:
 
+- `Visual Studio Code`_ (often shortened to "VS Code" or "vscode") is a
+  development-focused text editor that supports many programming languages in
+  addition to Python, includes an integrated terminal console, and has a rich
+  ecosystem of packages to extend its capabilities. Installing
+  `Microsoft's Python Extension
+  <https://marketplace.visualstudio.com/items?itemName=ms-python.python>`__ is
+  enough to get most Python users up and running. VS Code is free and
+  open-source.
 - `Spyder`_ is a free and open-source IDE developed by and for scientists who
   use Python. It is included by default in the ``base`` environment when you
   install Anaconda, and can be started from a terminal with the command
@@ -80,35 +108,33 @@ Python development are:
   Spyder to use the ``mne`` environment as its default interpreter by opening
   Spyder and navigating to
   :samp:`Tools > Preferences > Python Interpreter > Use the following interpreter`.
-  There, paste the output of the following terminal commands::
+  There, paste the output of the following terminal commands
+
+  .. code-block:: bash
 
-      $ conda activate mne
-      $ python -c "import sys; print(sys.executable)"
+      conda activate mne
+      python -c "import sys; print(sys.executable)"
 
   It should be something like ``C:\Users\user\anaconda3\envs\mne\python.exe``
   (Windows) or ``/Users/user/opt/anaconda3/envs/mne/bin/python`` (macOS).
 
   If the Spyder console can not start because ``spyder-kernels`` is missing,
   install the required version in the ``mne`` environment with the following
-  commands in the terminal::
+  commands in the terminal, where you replace ``...`` with the exact version of
+  ``spyder-kernels`` that Spyder tells you it requires.
+
+  .. code-block:: bash
 
-      $ conda activate mne
-      $ conda install spyder-kernels=HERE_EXACT_VERSION -c conda-forge
+      conda activate mne
+      conda install --strict-channel-priority --channel=conda-forge spyder-kernels=...
 
-  Refer to the `spyder documentation <https://docs.spyder-ide.org/current/troubleshooting/common-illnesses.html#spyder-kernels-not-installed-incompatible>`_
+  Refer to the `Spyder documentation <https://docs.spyder-ide.org/current/troubleshooting/common-illnesses.html#spyder-kernels-not-installed-incompatible>`_
   for more information about ``spyder-kernels`` and the version matching.
 
   If the Spyder graphic backend is not set to ``inline`` but to e.g. ``Qt5``,
-  ``pyqt`` must be installed in the ``mne`` environment.
+  ``PyQt5`` (``pip``) or ``pyqt`` (``conda``) must be installed in the ``mne``
+  environment.
 
-- `Visual Studio Code`_ (often shortened to "VS Code" or "vscode") is a
-  development-focused text editor that supports many programming languages in
-  addition to Python, includes an integrated terminal console, and has a rich
-  ecosystem of packages to extend its capabilities. Installing
-  `Microsoft's Python Extension
-  <https://marketplace.visualstudio.com/items?itemName=ms-python.python>`__ is
-  enough to get most Python users up and running. VS Code is free and
-  open-source.
 - `PyCharm`_ is an IDE specifically for Python development that provides an
   all-in-one installation (no extension packages needed). PyCharm comes in a
   free "community" edition and a paid "professional" edition, and is