From 45d056b2e97a39fef8ac86085282d86e0ab50a14 Mon Sep 17 00:00:00 2001 From: Tom Aldcroft Date: Tue, 10 Sep 2024 10:05:51 -0400 Subject: [PATCH] Rework install guide following from PR 16555 --- docs/install.rst | 196 +++++++++++++++-------------------------------- 1 file changed, 63 insertions(+), 133 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 89edf832365b..31314274ba6e 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -4,21 +4,45 @@ Installation ************ -.. _installing-astropy-with-conda: - -Installing Python and Astropy with Conda -**************************************** - -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. - -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``. +Overview +======== + +The first step to installing ``astropy`` is to ensure that you have a Python +environment which is **isolated** from your system Python installation. This is +important because ``astropy`` has many dependencies, and you do not want to accidentally +break your system by installing incompatible versions of these dependencies. + +For this installation guide we use the `conda `_ +package manager provided by `miniforge `_. +This is a popular choice and works well, especially for newcomers. It is easy to install +and use on all platforms and it makes it easy to install the latest Python version. If +you already have a ``miniforge``-based Python environment then you can skip to +:ref:`installing-astropy-with-pip`. + +Another option for more experienced users is a virtual environment manager such as the +Python standard library `venv `_ module. +There are numerous resources available to help you set up a virtual environment in this +manner if you choose this option. + +.. note:: + We **do not recommend** using ``astropy`` with an existing `miniconda + `_ or `Anaconda Python + `_ distribution. The default ``astropy`` package + provided by Anaconda Inc. can be outdated and these distributions can require a + license for use at a large organisation. Instead, use ``miniforge`` as described + below. + +Once you have a Python environment set up, you will install ``astropy`` using |pip| or +|conda|. Here we document using |pip| because it is easier to install the optional +dependencies, but feel free to use |conda| if you prefer. + +Install ``miniforge`` +===================== + +You will install Python by first installing `miniforge +`__. This provides the `conda +package manager `_ with the default remote package +repository set to the community-led `conda-forge `_ channel. First, download the installer for your system and architecture from the links below: @@ -39,9 +63,10 @@ First, download the installer for your system and architecture from the links be .. grid-item-card:: Mac + `arm64 (Apple Silicon) `__ + `x86-64 `__ - `arm64 (Apple Silicon) `__ Then select your platform to install miniforge: @@ -70,138 +95,43 @@ Then select your platform to install miniforge: 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 `__. - +Create a new environment +======================== -Installing astropy -================== - -To install ``astropy``, start by launching a terminal (under a UNIX-like system) or the miniforge Prompt (under Windows). +To create a new Python environment for ``astropy`` and other packages, 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 create --name astropy python $ 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. +In this case the environment we have created is named ``astropy`` but you can use any +name you like. -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. +In the future when you make a new terminal, you will need to run ``conda activate +astropy`` to activate this environment. .. _installing-astropy-with-pip: -Installing ``astropy`` with pip -******************************* - -.. warning:: - - 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:: - - python -m pip install astropy - -If you want to make sure none of your existing dependencies get upgraded, you -can also do:: - - python -m pip install astropy --no-deps - -On the other hand, if you want to install ``astropy`` along with recommended -or even all of the available optional :ref:`dependencies `, -you can do:: - - python -m pip install "astropy[recommended]" - -or:: - - python -m pip install "astropy[all]" - -In most cases, this will install a pre-compiled version (called a *wheel*) of -astropy, but if you are using a very recent version of Python, if a new version -of astropy has just been released, or if you are building astropy for a platform -that is not common, astropy will be installed from a source file. Note that in -this case you will need a C compiler to be installed -(see `Building from source`_ below) for the installation to succeed. - -If you get a ``PermissionError`` this means that you do not have the required -administrative access to install new packages to your Python installation. In -this case you should first create and activate a Python environment using either -:ref:`Conda ` or a `Python virtual -environment `__. Both of these options -will also allow you to do development on other software that uses -``astropy``, such as an affiliated package. - -.. warning:: Do **not** install ``astropy`` or other third-party packages using ``sudo``. - -.. _anaconda_install: - -Using Conda -=========== - -To install ``astropy`` using conda run:: - - conda install astropy - -``astropy`` is installed by default with the `Anaconda Distribution -`_. To update to the latest version run:: - - conda update astropy - -There may be a delay of a day or two between when a new version of ``astropy`` -is released and when a package is available for conda. You can check -for the list of available versions with ``conda search astropy``. - -If you want to install ``astropy`` along with recommended or all of the -available optional :ref:`dependencies `, you can do:: - - conda install --channel conda-forge --channel defaults scipy matplotlib - -or:: - - conda install --channel conda-forge --channel defaults scipy matplotlib \ - h5py beautifulsoup4 html5lib bleach pandas sortedcontainers \ - pytz setuptools mpmath bottleneck jplephem asdf-astropy pyarrow - -To also be able to run tests (see below) and support :ref:`builddocs` use the -following. We use ``pip`` for these packages to ensure getting the latest -releases which are compatible with the latest ``pytest`` and ``sphinx`` releases:: - - python -m pip install pytest-astropy sphinx-astropy +Install ``astropy`` +=================== -.. warning:: +To install ``astropy`` and your choice of :ref:`dependencies `, run +one of the following commands:: - 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 `. + python -m pip install astropy # Minimum required dependencies + python -m pip install "astropy[recommended]" # Recommended dependencies + python -m pip install "astropy[all]" # All optional dependencies + python -m pip install "astropy[dev_all]" # All optional and test dependencies -.. danger:: +.. warning:: Do **not** install ``astropy`` or other packages using ``sudo``. - Do **not** install ``astropy`` or other third-party packages using ``sudo``. +In most cases, this will install a pre-compiled version of ``astropy`` (called a +*wheel*). However, if you are installing astropy on an uncommon platform, astropy will be +installed from a source file. In this unusual case you will need a C compiler to be +installed (see `Building from source`_ below) for the installation to succeed. .. _testing_installed_astropy: