From f2c38c3b581917932041a50552718b66717e70b9 Mon Sep 17 00:00:00 2001 From: Stuart Mumford Date: Tue, 11 Jun 2024 11:11:38 +0100 Subject: [PATCH] Rewrite installation docs --- docs/install.rst | 131 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 118 insertions(+), 13 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 6d5a09dc7dfe..89edf832365b 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,26 +1,126 @@ +.. _installing-astropy: + ************ Installation ************ -.. _installing-astropy: +.. _installing-astropy-with-conda: -Installing ``astropy`` -********************** +Installing Python and Astropy with Conda +**************************************** -If you are new to Python and/or do not have familiarity with `Python virtual -environments `__, then we recommend -starting by installing the `Anaconda Distribution -`_. This works on all platforms (linux, -Mac, Windows) and installs a full-featured scientific Python in a user directory -without requiring root permissions. +There are many ways to install Python, but even if you have Python installed somewhere on your computer we recommend following these instructions anyway. +The easiest way to manage a Python installation together with an Astropy installation is with the ``conda`` package manager. +If you already have Python and ``conda`` working you can skip the next section. +However, if you are using the Anaconda Python Distribution, we recommend you still install miniforge as described below. -Using pip -========= +Installing miniforge +==================== + +We recommend installing Python with `miniforge `__. +This will install ``conda`` and automatically configure the default channel (a channel is a remote software repository) to be ``conda-forge``. + +First, download the installer for your system and architecture from the links below: + +.. grid:: 3 + + .. grid-item-card:: Linux + + `x86-64 `__ + + `aarch64 `__ + + `ppc64le `__ + + .. grid-item-card:: Windows + :link: https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe + + `x86-64 `__ + + .. grid-item-card:: Mac + + `x86-64 `__ + + `arm64 (Apple Silicon) `__ + +Then select your platform to install miniforge: + +.. tab-set:: + + .. tab-item:: Linux & Mac + :sync: platform + + Linux & Mac Run the script downloaded above, with + ``bash ``. The following should work: + + .. code-block:: console + + bash Miniforge3-$(uname)-$(uname -m).sh + + Once the installer has completed, close and reopen your terminal. + + .. tab-item:: Windows + :sync: platform + + Double click the executable file downloaded from + the links above. + + Once the installer has completed you should have a new "miniforge + Prompt" entry in your start menu. + +In a new terminal (miniforge Prompt on Windows) run ``conda list`` to test that the install has worked. + +Using an Existing Conda Installation +==================================== + +If you already have a conda installation you can use it to install astropy. +We do not recommend reusing an anaconda installation, as the default packages provided by Anaconda Inc. are often out dated and can require a license for use at a large organisaiton. +If you have installed miniforge or anaconda you can add ``-c conda-forge`` to all installation commands to install packages from `conda-forge `__. + + +Installing astropy +================== + +To install ``astropy``, start by launching a terminal (under a UNIX-like system) or the miniforge Prompt (under Windows). +Now we will create and activate a new virtual environment to install ``astropy`` into: + +.. code-block:: bash + + $ conda create --name astropy + $ conda activate astropy + +In this case the environment we have created is named 'astropy'. +Feel free to change this to a different environment name. + +The benefit of using a virtual environment is that it allows you to install packages without affecting any other Python installation on your system. +This also means you can work on multiple projects (research or coding) with different package requirements without them interfering with each other. + +Now we have a fresh environment we can install ``astropy``: + +.. code-block:: bash + + $ conda install astropy + +This will install ``astropy`` and all of its dependencies. +If you want to install another package later, you can run ``conda install ``. + +You will need to run ``conda activate astropy`` to activate this environment in new terminals in the future. + +.. _installing-astropy-with-pip: + +Installing ``astropy`` with pip +******************************* .. warning:: - Users of the Anaconda Python distribution should follow the instructions - for :ref:`anaconda_install`. + If you are new to Python and/or do not have familiarity with `Python virtual + environments `__, then we recommend + starting following the conda instructions above. + +Using pip +========= + +We highly recommended that you create a virtual environment before installing astropy. To install ``astropy`` with |pip|, run:: @@ -97,6 +197,11 @@ releases which are compatible with the latest ``pytest`` and ``sphinx`` releases Attempting to use `pip `__ to upgrade your installation of ``astropy`` itself may result in a corrupted installation. +this case you should create a :ref:`virtual environment `. + +.. danger:: + + Do **not** install ``astropy`` or other third-party packages using ``sudo``. .. _testing_installed_astropy: