diff --git a/content/en/beginner-install.md b/content/en/beginner-install.md new file mode 100644 index 00000000..1c871bca --- /dev/null +++ b/content/en/beginner-install.md @@ -0,0 +1,75 @@ +--- +title: Beginner Installation Guide +sidebar: false +--- + +{{< admonition tip >}} +This is the beginner installation guide. +If you are comfortable with using a terminal and happy to learn +how to use a package manager, check out +[the main installation guide](./install.md)! +{{< /admonition >}} + +- [JupyterLite](#jupyterlite) +- [Scientific Python Distributions](#distributions) +- [Installing globally with `pip`](#pip-global) + + + +## JupyterLite + +To try out SciPy, you don't even need to install it! +You can use SciPy in your browser at https://jupyter.org/try-jupyter/lab/ - +just open a Python Notebook, then write `import scipy` in one of +the notebook "cells" and hit play. + +For next steps, see [the SciPy user guide][scipy-user-guide]. + +[scipy-user-guide]: https://docs.scipy.org/doc/scipy/tutorial/ + + + +## Scientific Python Distributions + +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 +most commonly used scientific Python tools. +[Anaconda](https://www.anaconda.com/download/) works on Windows, Mac, +and Linux, and is best suited to beginning users. +Other options include: + +- [WinPython](https://winpython.github.io): Another free distribution + including scientific packages and the Spyder IDE; Windows only. +- [Pyzo](https://pyzo.org): A free distribution based on Anaconda + and the IEP interactive development environment; Supports Linux, + Windows, and Mac. + +{{< admonition note >}} +Anaconda is free to use for inviduals, universities, and companies smaller than +200 employees. For more detail, see Anaconda's helpful blog on +["when is Anaconda free to use?"](https://www.anaconda.com/blog/update-on-anacondas-terms-of-service-for-academia-and-research) +{{< /admonition >}} + +After installing a scientific Python distribution, +see next steps in [the SciPy user guide][scipy-user-guide]. + + + +## Installing globally with `pip` + +If you already have Python installed, you can install SciPy +with `pip` by executing the following in a terminal/shell: + + python -m pip install scipy + +{{< admonition warning >}} +You may see this recommended in tutorials or classes, but the recommended +way to install SciPy with `pip` is to use a virtual environment - +see [Installing with `pip`](./install.md#installing-with-pip). +{{< /admonition >}} + +{{< admonition note >}} +For more information on why this is not a recommended installation method, +read about [virtual environments in the Python Packaging User Guide](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments). +{{< /admonition >}} diff --git a/content/en/install.md b/content/en/install.md index 7b1399f2..c7a445ab 100644 --- a/content/en/install.md +++ b/content/en/install.md @@ -3,101 +3,230 @@ title: Installation sidebar: false --- -Installations methods include: +{{< admonition tip >}} +This page assumes that you are comfortable with using a terminal and happy to learn +how to use a package manager. If you are a beginner and just want to get started +with SciPy as quickly as possible, check out +[the beginner installation guide](./beginner-install.md)! +{{< /admonition >}} -- [Distributions](#distributions) -- [pip](#pip-install) -- [conda](#pip-install) -- [Package Manager](#package_manager) -- [Source](#source) +The recommended method of installing SciPy depends on your preferred workflow. +The common workflows can roughly be broken down into the following +categories: -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/). +- [Project-based (e.g. `uv`, `pixi`)](#project-based) (recommended for new users) +- [Environment-based (e.g. `pip`, `conda`)](#environment-based) (the traditional workflow) +- [System package managers](#system-package-managers) (not recommended) +- [Building from source](#building-from-source) (for debugging and development) - +To install SciPy with [static type stubs], +see [Installing with type stubs](#type-stubs). -# Scientific Python Distributions (recommended) +[static type stubs]: https://typing.readthedocs.io/en/latest/guides/libraries.html -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. + -[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. +## Project-based workflows -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. +### Installing with `uv` -Other options include: +Here is a step-by-step guide to setting up a project to use SciPy, with [`uv`], +a Python package manager. -- [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. +[`uv`]: https://docs.astral.sh/uv/ - + -# Installing with Pip +1. Install `uv`, following [the instructions in the `uv` documentation][install-uv]. -You can install SciPy from PyPI with `pip`: +[install-uv]: https://docs.astral.sh/uv/getting-started/installation/ - python -m pip install scipy +2. Create a new project in a new subdirectory, by executing the following in a terminal: - + uv init try-scipy + cd try-scipy -# Installing via Conda + {{< admonition hint >}} +The second command changes directory into the directory of your project. + {{< /admonition >}} -You can install SciPy from the `defaults` or `conda-forge` channels with `conda`: +3. Add SciPy to your project: - conda install scipy + uv add scipy - + {{< admonition note >}} +This will automatically install Python if you don't already have it installed! + {{< /admonition >}} -# Install system-wide via a package manager + {{< admonition tip >}} +You can install other Python libraries in the same way, e.g. + + uv add matplotlib + + {{< /admonition >}} + +4. Try out SciPy! + + uv run python + + This will launch a Python interpreter session, from which you can `import scipy`. + + + +See next steps in [the SciPy user guide][scipy-user-guide]. + +[scipy-user-guide]: https://docs.scipy.org/doc/scipy/tutorial/ + +{{< admonition note >}} + +After rebooting your computer, you'll want to navigate to your `try-scipy` +project directory and execute `uv run python` to drop back into a Python interpreter +with SciPy importable. +To execute a Python script, you can use `uv run myscript.py`. + +Read more at [the uv guide to working on projects][uv-projects]. + +[uv-projects]: https://docs.astral.sh/uv/guides/projects/ + +{{< /admonition >}} + +### Installing with `pixi` + +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](https://pypi.org/), the Python Package Index. +Conda can manage packages in any language, so you can use it to install +Python itself, compilers, and other languages. + +[Conda]: https://docs.conda.io/projects/conda/en/latest/index.html + +The steps to install SciPy from [conda-forge] using the package management +tool [`pixi`] are very similar to the steps for `uv`: + +[conda-forge]: https://conda-forge.org/ +[`pixi`]: https://pixi.sh/latest/ + +1. Install `pixi`, following [the instructions in the `pixi` documentation][install-pixi]. + +[install-pixi]: https://pixi.sh/latest/ + +2. Create a new project in a new subdirectory: + + pixi init try-scipy + cd try-scipy + +3. Add SciPy to your project: + + pixi add scipy + +4. Try out SciPy! + + pixi run python + +See next steps in [the SciPy user guide][scipy-user-guide]. + + + +## Environment-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. + +In contrast, +in environment-based workflows you install packages into an environment, +which you can activate and deactivate from any directory. +These workflows are well-established, +but lack some reproducibility benefits of project-based workflows. + +### Installing with `pip` + + + +1. [Install Python](https://www.python.org/downloads/). + +2. Create and activate a virtual environment with `venv`. + + {{< admonition hint >}} +See [the tutorial in the Python Packaging User Guide](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments). + {{< /admonition >}} + +3. Install SciPy, using [`pip`]: + + python -m pip install scipy + + + +[`pip`]: https://pip.pypa.io/en/stable/getting-started/ + +### Installing with `conda` + +[Miniforge] is the recommended way to install `conda` and [`mamba`], +two Conda-based environment managers. +After creating an environment, you can install SciPy from conda-forge as follows: + + conda install scipy # or + mamba install scipy + +[Miniforge]: https://conda-forge.org/download/ +[`mamba`]: https://mamba.readthedocs.io/en/latest/ + + + +## 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. -## 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 - + -# 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 + + + +## Installing with type stubs + +Static type stubs are available via a separate package, `scipy-stubs`, on +PyPI and conda-forge. +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.*`, for example: + + uv add "scipy-stubs[scipy]==1.14.1.*" # or + pixi add "scipy-typed=1.15.0.*" # or + python -m pip install "scipy-stubs[scipy]" # or + conda install "scipy-typed>=1.14" + +Please direct questions about static typing support to +[the `scipy-stubs` GitHub repository](https://github.com/jorenham/scipy-stubs).