Rewrite installation docs to not recommend anaconda / defaults channel#16555
Rewrite installation docs to not recommend anaconda / defaults channel#16555Cadair wants to merge 1 commit into
Conversation
|
Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.
|
| <https://www.anaconda.com/download/>`_. 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. |
There was a problem hiding this comment.
| There are many ways to install Python, but even if you have Python installed somewhere on your computer we recommend following these instructions anyway. | |
| There are many ways to install Python, but even if you have Python installed somewhere on your computer we recommend following these instructions. |
| `x86-64 <https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-x86_64.sh>`__ | ||
|
|
||
| `arm64 (Apple Silicon) <https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh>`__ |
There was a problem hiding this comment.
I'd suggest puttin arm64 first since it's more and more common and should soon become the only used macOS arch (written from my x86-64 2018 macbook)
| ==================================== | ||
|
|
||
| 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. |
There was a problem hiding this comment.
| 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. | |
| 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 organisation. |
|
|
||
| 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 <https://conda-forge.org>`__. |
There was a problem hiding this comment.
Maybe a good place to also mention how to do it permanently ?
conda config --prepend channels conda-forge
There was a problem hiding this comment.
I got myself stuck in a bit of a brain loop with this. You could write a whole essay on how to unravel yourself out of a defaults / anaconda install and not get shot in the foot.
sunpy has this:
conda config --add channels conda-forge
conda config --set channel_priority strict
which is a good thing to have, but if you have installed miniforge then you don't need to run it, and if you have full-fat anaconda then running them has the potential to really break your base environment. So I am not sure what the best thing to recommend to people who really want to use Anaconda or don't want to install a new miniforge.
There was a problem hiding this comment.
Right. We should probably keep it simple and repeatable then. Users who get tired of typing -c conda-forge can figure out how to skip it easily enough.
| $ conda create --name astropy | ||
| $ conda activate astropy |
There was a problem hiding this comment.
To avoid confusing first-time users, I think it might be preferable to use a distinctive name for then environment itself
| $ conda create --name astropy | |
| $ conda activate astropy | |
| $ conda create --name astropy-env | |
| $ conda activate astropy-env |
| $ conda create --name astropy | ||
| $ conda activate astropy | ||
|
|
||
| In this case the environment we have created is named 'astropy'. |
There was a problem hiding this comment.
| In this case the environment we have created is named 'astropy'. | |
| In this case the environment we have created is named 'astropy-env'. |
| This will install ``astropy`` and all of its dependencies. | ||
| If you want to install another package later, you can run ``conda install <package_name>``. | ||
|
|
||
| You will need to run `conda activate astropy` to activate this environment in new terminals in the future. |
There was a problem hiding this comment.
| You will need to run `conda activate astropy` to activate this environment in new terminals in the future. | |
| You will need to run `conda activate astropy-env` to activate this environment in new terminals in the future. |
|
|
||
| Attempting to use `pip <https://pip.pypa.io>`__ to upgrade your installation | ||
| of ``astropy`` itself may result in a corrupted installation. | ||
| Do **not** install ``astropy`` or other third-party packages using ``sudo``. |
|
RTD build failed. |
52f4043 to
9b9c3ec
Compare
|
I thought we decided in the past to first recommend pip, then conda, pip being the 'standard' way and working fine now with wheels? |
There have always been diffs of opinion, but we did decide at one point to recommend conda first. In any case that is out of scope for this PR. 😄 |
|
I have put conda at the top in this PR. I think that's it's a better recommendation for most people. |
|
@taldcroft - well it is in scope of this PR currently as this changes the current order. Currently the docs recommend pip first. |
| We recommend installing Python with `miniforge <https://github.com/conda-forge/miniforge/#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: |
There was a problem hiding this comment.
I am not sure if we want to maintain a list of installers here. We are not a miniforge documentation. I don't feel like this is our job.
There was a problem hiding this comment.
I think this is easy to do, and the miniforge documentation is rubbish to non-existent so it makes life a lot easier for users for minimal pain for us.
There was a problem hiding this comment.
also, installers will change and their locations will move...
There was a problem hiding this comment.
miniforge not having nice doc is not our problem to solve, or if you want to solve that, it isn't here. I am okay with suggesting to use miniforge but I do not want our doc to turn into their doc.
There was a problem hiding this comment.
and the miniforge documentation is rubbish to non-existent
@Cadair - Is this what you were talking about?
https://github.com/conda-forge/miniforge/blob/main/README.md
I agree your version is prettier and nicer, but it seems like that README has the basic information on download and install. Maybe it's good enough?
There was a problem hiding this comment.
I think it really sucks if we make users click out to an inferior set of documentation (clicking out alone is friction) vs keeping like 6 links in our docs. If we contribute upstream in the future and make things better then sure let's get rid of it.
There was a problem hiding this comment.
Since that issue to make a nice download page has been open for nearly 4 years, I think we should just use the nice one that @Cadair has create for astropy. Maybe if this is brought to their attention they will use and maintain it, but in the meantime let's not stall this useful PR!
Good catch, I didn't notice that change. In general I think we should start with conda, and at some point we had a discussion and decided that (on the whole) conda is more accessible to beginners than pip + pip-environments. That said, if this is controversial then this PR could just revert the order. |
|
|
||
| .. code-block:: bash | ||
|
|
||
| $ conda install astropy |
There was a problem hiding this comment.
At this point I think we should recommend the pip install path for installing astropy. conda is great for creating the base Python isolated (or "virtual") environment, but pip works better for installing the rest. In particular it is much easier to specify additional dependencies recommended or all. conda install astropy installs only minimal dependencies and there is no easy way to get the recommended or all dependencies.
Instead, start with:
conda create -n astropy-env python
Then say "Now install astropy using pip as described in the next section."
There was a problem hiding this comment.
fwiw, i completely agree with this and have recommended this approach in other contexts for the stated reasons. conda is great for pulling in the proverbial kitchen sink, but if you want to fine-tune what you install, pip is a much better approach.
taldcroft
left a comment
There was a problem hiding this comment.
@Cadair - I agree with the suggestions from @neutrinoceros. With those and a few more that I just put in, this should be good to go.
| for :ref:`anaconda_install`. | ||
| If you are new to Python and/or do not have familiarity with `Python virtual | ||
| environments <https://docs.python.org/3/tutorial/venv.html>`_, then we recommend | ||
| starting following the conda instructions above. |
There was a problem hiding this comment.
| starting following the conda instructions above. | |
| starting with the conda instructions above. |
|
|
||
| .. code-block:: bash | ||
|
|
||
| $ conda create --name astropy |
There was a problem hiding this comment.
Per my comment below about always using pip to install astropy:
| $ conda create --name astropy | |
| $ conda create -c conda-forge --name astropy-env python |
|
How about we remove the miniforge installer stuff, and keep this as simple as possible? |
@pllim - counting the 👍 from @neutrinoceros, it is 3 in favor of the grid and 1 against. |
|
I still feel like the miniforge installation stuff is more useful being elsewhere, like maybe the OpenAstronomy guide or Scientific Python guide. |
Perfect is the enemy of good. We're just trying to get something good done in finite time. |
|
The docs is bound to be moved, and then everyone's links would break. It would create extra churn in the future. I can almost guarantee it. |
I'm happy to accept that risk for the immediate benefit of thousands of users having a better experience installing astropy. |
|
But @Cadair , how hard is it to just move the miniforge install stuff somewhere into OpenAstronomy land and then link to that from here? Then all the other projects can also benefit from these instructions without having to point to astropy docs. |
|
Coming back to this following some discussions at the NumFOCUS summit. There's a pretty strong recommendation coming out of that crowd that I've made astropy/astropy.github.com#617 to also update this on the web page with that in mind, but I can adjust that to match whatever consensus we reach here. (I am happy update this PR to reflect this but first want to make sure people are comfortable with that before I do so. I suppose especially @Cadair ) |
|
Just out of curiosity, does vanilla conda work ok with conda-forge these days? In the past I found it to be incredibly slow due to the number of packages/versions on conda-forge, and mamba was a much better choice, which is included by default in miniforge I believe? If so, we should maybe even recommend using the mamba command over conda? |
|
Latest few conda releases use libmamba for the solver so should be fine now aiui. |
|
@eteq are you suggesting removing the section on -c conda-forge? We already call out that we don't recommend it and you might need a license? |
|
Yes, that's exactly what I was suggesting @Cadair . I had thought that the |
|
I still don't like how this PR turns our doc into miniforge install help desk. I think that content should go upstream, say, OpenAstronomy at least. Also there is a conflict now. |
|
I think right now we are actively encouraging the community to do something that is creating a problem for them by having it in the docs. Not changing this or waiting for it to go upstream just perpetuates that. As @taldcroft said, the perfect can't be the enemy of the good here. It's also worth highlighting (since I don't see in this thread), I think we agreed in the coordination meeting we should do this given the impact on our user community of the license changes. I think we just didn't realize at the time that just |
|
I put this topic down for the next scheduled dev telecon on 2024-10-03 |
|
This PR has been sitting for quite a while, honestly I was surprised to see it hasn't been merged given the outcome of the coordination meeting discussion that we should do what @Cadair implemented. Aside from the conda -> miniforge switch (which the NumFOCUS infrastructure committee is likely going to be putting out a statement recommending shortly now that people better understand the anaconda licensing rules), I think it's better to get this in ASAP and not wait on the developer telecon to re-litigate this. (Not that we shouldn't discuss it in the telecon! Just that I'm suggesting we could merge this with the updates and we can always update it again later if there is a change from the dev telecon.) |
|
@Cadair @eteq @pllim @neutrinoceros -- I've taken a crack at getting this PR across the finish line with #16987. 🤞 |
…rework Rework Install guide following on from #16555
|
Thanks, all! |
|
For completeness, we just merged astropy/astropy.github.com#617 as well. |
Description
This PR strongly recommends people install astropy with conda and the conda-forge channel. It explicitly recommends against using the anaconda distribution. It also explicitly recommends virtual environments everywhere.
This is heavily inspired by the sunpy documentation