Skip to content

Commit

Permalink
simplify python install instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@drammock
drammock committed Oct 2, 2023
1 parent 8b56b91 commit 14a9246
Show file tree
Hide file tree
Showing 3 changed files with 14 additions and 182 deletions.
41 changes: 0 additions & 41 deletions doc/install/advanced.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -102,47 +102,6 @@ just prefer to use git rather than pip to make frequent updates, there are
instructions for installing from a ``git clone`` in the :ref:`contributing`.


.. _other-py-distros:

Other Python distributions
^^^^^^^^^^^^^^^^^^^^^^^^^^

While the `Anaconda`_ Python distribution provides many conveniences, other
distributions of Python should also work with MNE-Python. In particular,
`Miniconda`_ is a lightweight alternative to Anaconda that is fully compatible;
like Anaconda, Miniconda includes the ``conda`` command line tool for
installing new packages and managing environments; unlike Anaconda, Miniconda
starts off with a minimal set of around 30 packages instead of Anaconda's
hundreds. See the `installation instructions for Miniconda`_ for more info.
A similar alternative is `MiniForge`_, which uses the ``conda-forge`` channel
as the default source for package installation (saving you the trouble of
typing ``--channel=conda-forge`` with each ``conda install`` command).

.. warning::

If you have the ``PYTHONPATH`` or ``PYTHONHOME`` environment variables set,
you may run into difficulty using Anaconda. See the
`Anaconda troubleshooting guide`_ for more information. Note that it is
easy to switch between ``conda``-managed Python installations and the
system Python installation using the ``conda activate`` and ``conda
deactivate`` commands, so you may find that after adopting Anaconda it is
possible (indeed, preferable) to leave ``PYTHONPATH`` and ``PYTHONHOME``
permanently unset.


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
$ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/main/requirements.txt
$ pip install --user -r requirements.txt
Other configurations will probably also work, but we may be unable to offer
support if you encounter difficulties related to your particular Python
installation choices.

.. _CUDA:

GPU acceleration with CUDA
Expand Down
154 changes: 13 additions & 141 deletions doc/install/manual_install_python.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,151 +3,23 @@
.. _install-python:

Installing Python
^^^^^^^^^^^^^^^^^
=================

MNE-Python requires Python and several Python packages. MNE-Python
version |version| requires Python version |min_python_version| or higher. We
recommend the `Anaconda`_ distribution of Python, which comes with more than
250 scientific packages pre-bundled and includes the ``conda`` command line
tool for installing new packages and managing different package sets
("environments") for different projects.
version |version| requires Python version |min_python_version| or higher.

To get started, follow the `installation instructions for Anaconda`_.
When you are done, if you type the following commands in a command shell,
you should see outputs similar to the following (assuming you installed
conda to ``/home/user/anaconda3``):
We recommend using a conda-based Python installation, such as `Anaconda`_, `Miniconda`_,
`MiniForge`_, or `Mambaforge`_. For new users we recommend our pre-built `installers`_,
which use conda environments under the hood.


.. tab-set::
:class: platform-selector-tabset
.. _other-py-distros:

.. tab-item:: Linux
:name: linux-manual-install
Other Python distributions
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console
$ conda --version && python --version
conda 4.9.2
Python 3.8.13 :: Anaconda, Inc.
$ which python
/home/user/anaconda3/bin/python
$ which pip
/home/user/anaconda3/bin/pip
.. tab-item:: macOS
:name: macos-manual-install

.. code-block:: console
$ conda --version && python --version
conda 4.9.2
Python 3.8.13
$ which python
/Users/user/opt/anaconda3/bin/python
$ which pip
/Users/user/opt/anaconda3/bin/pip
.. tab-item:: Windows
:name: windows-manual-install

Most of our instructions start with ``$``, which indicates
that the commands are designed to be run from a ``bash`` command shell.

Windows command prompts do not expose the same command-line tools as
``bash`` shells, so commands like ``which`` will not work. You can test
your installation in Windows ``cmd.exe`` shells with ``where`` instead:

.. code-block:: doscon
> where python
C:\Users\user\anaconda3\python.exe
> where pip
C:\Users\user\anaconda3\Scripts\pip.exe
.. raw:: html

<div width="100%" height="0 px" style="margin: 0 0 15px;"></div>


.. dropdown:: If you get an error...
:color: danger
:icon: alert-fill

.. rubric:: If you see something like:

::

conda: command not found

It means that your ``PATH`` variable (what the system uses to find
programs) is not set properly. In a correct installation, doing::

$ echo $PATH
...:/home/user/anaconda3/bin:...

Will show the Anaconda binary path (above) somewhere in the output
(probably at or near the beginning), but the ``command not found`` error
suggests that it is missing.

On Linux or macOS, the installer should have put something
like the following in your ``~/.bashrc`` or ``~/.bash_profile`` (or your
``.zprofile`` if you're using macOS Catalina or later, where the default
shell is ``zsh``):

.. code-block:: console
# >>> conda initialize >>>
# !! Contents within this block are managed by 'conda init' !!
__conda_setup= ...
...
# <<< conda initialize <<<
If this is missing, it is possible that you are not on the same shell that
was used during the installation. You can verify which shell you are on by
using the command::

$ echo $SHELL

If you do not find this line in the configuration file for the shell you
are using (bash, zsh, tcsh, etc.), try running::

conda init

in your command shell. If your shell is not ``cmd.exe`` (Windows) or
``bash`` (Linux, macOS) you will need to pass the name of the shell to the
``conda init`` command. See ``conda init --help`` for more info and
supported shells.

You can also consult the Anaconda documentation and search for
Anaconda install tips (`Stack Overflow`_ results are often helpful)
to fix these or other problems when ``conda`` does not work.


.. raw:: html

<script type="text/javascript">
var platform = "linux";
if (navigator.userAgent.indexOf("Win") !== -1) {
platform = "windows";
}
if (navigator.userAgent.indexOf("Mac") !== -1) {
platform = "macos";
}
$(document).ready(function(){
let all_tab_nodes = document.querySelectorAll(
'.platform-selector-tabset')[0].children;
let input_nodes = [...all_tab_nodes].filter(
child => child.nodeName === "INPUT");
let tab_label_nodes = [...document.querySelectorAll('.sd-tab-label')];
let correct_label = tab_label_nodes.filter(
// label.id is drawn from :name: property in the rST, which must
// be unique across the whole site (*sigh*)
label => label.id.startsWith(platform))[0];
let input_id = correct_label.getAttribute('for');
let correct_input = input_nodes.filter(node => node.id === input_id)[0];
correct_input.checked = true;
});
</script>
While conda-based CPython distributions provide many conveniences, other types of
installation (``pip`` / ``poetry``, ``venv`` / system-level) and/or other Python
distributions (PyPy) *should* also work with MNE-Python. Generally speaking, if you can
install SciPy, getting MNE-Python to work should be unproblematic. Note however that we
do not offer installation support for anything other than conda-based installations.
1 change: 1 addition & 0 deletions doc/links.inc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@
.. _anaconda: https://www.anaconda.com/products/individual
.. _miniconda: https://conda.io/en/latest/miniconda.html
.. _miniforge: https://github.com/conda-forge/miniforge
.. _mambaforge: https://mamba.readthedocs.io/en/latest/mamba-installation.html#mamba-install
.. _installation instructions for Anaconda: http://docs.continuum.io/anaconda/install
.. _installation instructions for Miniconda: https://conda.io/projects/conda/en/latest/user-guide/install/index.html
.. _Anaconda troubleshooting guide: http://conda.pydata.org/docs/troubleshooting.html
Expand Down

0 comments on commit 14a9246

Please sign in to comment.