Update installation page

content/en/install.md

@@ -3,101 +3,149 @@ title: Installation
 sidebar: false
 ---
 
-Installations methods include:
+The recommended method of installing SciPy depends on your preferred workflow.
+The common workflows can roughly be broken down into the following
+categories:
 
-- [Distributions](#distributions)
-- [pip](#pip-install)
-- [conda](#pip-install)
-- [Package Manager](#package_manager)
-- [Source](#source)
+- [Environment-based (e.g. `pip`, `conda`)](#environment-based) (the traditional workflow)
+- [Project-based (e.g. `uv`, `pixi`)](#project-based) (recommended for new users)
+- [System package managers](#system-package-managers) (simplest)
+- [Building from source](#building-from-source) (for debugging and development)
 
-Methods differ in ease of use, coverage, maintenance of old versions,
-system-wide versus local environment use, and control. With pip or
-Anaconda\'s conda, you can control the package versions for a specific
-project to prevent conflicts. Conda also controls non-Python packages,
-like MKL or HDF5. System package managers, like `apt-get`, install
-across the entire computer, often have older versions, and don\'t have
-as many available versions. Source compilation is much more difficult
-but is necessary for debugging and development. If you don\'t know which
-installation method you need or prefer, we recommend the Scientific
-Python Distribution [Anaconda](https://www.anaconda.com/download/).
+To install SciPy with [static type stubs],
+see [Installing with type stubs](#type-stubs).
 
-<a name="distributions"></a>
+[static type stubs]: https://typing.readthedocs.io/en/latest/guides/libraries.html
 
-# Scientific Python Distributions (recommended)
+<a name="environment-based"></a>
 
-Python distributions provide the language itself, along with the most
-commonly used packages and tools. These downloadable files require
-little configuration, work on almost all setups, and provide all the
-commonly used scientific Python tools.
+## Environment-based workflows
 
-[Anaconda](https://www.anaconda.com/download/) works on Windows, Mac,
-and Linux, provides over 1,500 Python packages, and is used by over 15
-million people. Anaconda is best suited to beginning users; it provides
-a large collection of libraries all in one.
+In environment-based workflows, you install packages into an environment, which you
+can activate and deactivate.
 
-For more advanced users who will need to install or upgrade regularly,
-[Mambaforge](https://github.com/conda-forge/miniforge#mambaforge) is a more
-suitable way to install the `conda` (and `mamba`, a faster `conda` alternative)
-package manager.
+If you have installed Python, you can create a virtual environment with a tool such
+as `venv` - see [the tutorial in the Python Packaging User Guide][venv-guide].
+You can then install [SciPy from PyPI], the Python Package Index, with [`pip`]:
 
-Other options include:
+    python -m pip install scipy
 
-- [WinPython](https://winpython.github.io): Another free distribution
-  including scientific packages and the Spyder IDE; Windows only, but
-  more actively maintained and supports the latest Python 3 versions.
-- [Pyzo](https://pyzo.org): A free distribution based on Anaconda
-  and the IEP interactive development environment; Supports Linux,
-  Windows, and Mac.
+[venv-guide]: https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments
+[SciPy from PyPI]: https://pypi.org/project/scipy/
+[`pip`]: https://pip.pypa.io/en/stable/getting-started/
 
-<a name="pip-install"></a>
+Alternatively, you can install [SciPy from conda-forge] using a [Conda]-based
+environment manager. You can install Python itself, as well as packages in
+languages other than Python, as Conda packages.
 
-# Installing with Pip
+[Miniforge] is the recommended way to install `conda` and [`mamba`],
+two Conda-based environment managers. You can then install SciPy as follows:
 
-You can install SciPy from PyPI with `pip`:
+    conda install scipy # or
+    mamba install scipy
 
-    python -m pip install scipy
+[SciPy from conda-forge]: https://anaconda.org/conda-forge/scipy
+[Miniforge]: https://conda-forge.org/download/
+[Conda]: https://docs.conda.io/projects/conda/en/latest/index.html
+[`mamba`]: https://mamba.readthedocs.io/en/latest/
+
+<a name="project-based"></a>
+
+## Project-based workflows
+
+In project-based workflows, a project is a directory containing a manifest
+file describing the project, a lock-file describing the exact dependencies
+of the project, and the project's (potentially multiple) environments.
+These workflows provide reproducibility benefits over environment-based workflows.
+
+You can add [SciPy from PyPI] to a [`uv`] project:
+
+    uv add scipy
+
+You can also install Python itself with `uv`.
+
+[`uv`]: https://docs.astral.sh/uv/
+
+If you work with non-Python packages, you may prefer to install SciPy as
+a Conda package, so that you can use the same workflow for packages which
+are not available on PyPI.
 
-<a name="conda-install"></a>
+You can add [SciPy from conda-forge] to a [`pixi`] project:
 
-# Installing via Conda
+    pixi add scipy
 
-You can install SciPy from the `defaults` or `conda-forge` channels with `conda`:
+Pixi can also install packages from PyPI, using `uv` under the hood.
 
-    conda install scipy
+[`pixi`]: https://pixi.sh/latest/
 
-<a name="package_manager"></a>
+<a name="system-package-managers"></a>
 
-# Install system-wide via a package manager
+## Installing system-wide via a system package manager
 
 System package managers can install the most common Python packages.
 They install packages for the entire computer, often use older versions,
-and don't have as many available versions.
+and don't have as many available versions. They are not the recommended
+installation method, but they are the simplest.
 
-## Ubuntu and Debian
+### Ubuntu and Debian
 
 Using `apt-get`:
 
     sudo apt-get install python3-scipy
 
-## Fedora
+### Fedora
 
 Using `dnf`:
 
     sudo dnf install python3-scipy
 
-## macOS
+### macOS
 
 macOS doesn't have a preinstalled package manager, but you can install
 [Homebrew](https://brew.sh/) and use it to install SciPy (and Python itself):
 
     brew install scipy
 
-<a name="source"></a>
+<a name="building-from-source"></a>
 
-# Source packages
+## Building from source
 
 A word of warning: building SciPy from source can be a nontrivial exercise. We
-recommend using binaries instead if those are available for your platform.
+recommend using binaries instead if those are available for your platform
+via one of the above methods.
 For details on how to build from source, see
-[this guide in the SciPy docs](https://scipy.github.io/devdocs/building/index.html).
+[the building from source guide in the SciPy docs][building-docs].
+
+[building-docs]: https://scipy.github.io/devdocs/building/index.html
+
+<a name="type-stubs"></a>
+
+## Installing with type stubs
+
+Static type stubs are available via a separate package, `scipy-stubs`, on
+PyPI and conda-forge. If you have already installed SciPy, you just need to
+install `scipy-stubs` in the same way:
+
+    python -m pip install scipy-stubs # or
+    uv add scipy-stubs # or
+    conda install scipy-stubs # or
+    pixi add scipy-stubs
+
+<!---
+XXX: https://github.com/conda-forge/scipy-stubs-feedstock/pull/5
+-->
+
+You can also install SciPy and `scipy-stubs` as a single package,
+via the `scipy-stubs[scipy]` extra on PyPI, or the `scipy-typed`
+package on conda-forge.
+To get a specific version `x.y.z` of SciPy (such as `1.14.1`),
+you should install version `x.y.z.*` below:
+
+    python -m pip install "scipy-stubs[scipy]" # or
+    # versions for illustrative purposes
+    uv add "scipy-stubs[scipy]==1.14.1.*" # or
+    conda install "scipy-typed>=1.14" # or
+    pixi add "scipy-typed=1.15.0.*"
+
+Please direct questions about static typing support to
+[the `scipy-stubs` GitHub repository](https://github.com/jorenham/scipy-stubs).