Skip to content

Commit

Permalink
Update installation page (#595)
Browse files Browse the repository at this point in the history
  • Loading branch information
@lucascolley
lucascolley authored Dec 23, 2024
1 parent 4aae151 commit 4c947a9
Show file tree
Hide file tree
Showing 2 changed files with 259 additions and 55 deletions.
75 changes: 75 additions & 0 deletions content/en/beginner-install.md
View file
Original file line number Diff line number Diff line change
@@ -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)

<a name="jupyterlite"></a>

## 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/

<a name="distributions"></a>

## 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].

<a name="pip-global"></a>

## 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 >}}
239 changes: 184 additions & 55 deletions content/en/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<a name="distributions"></a>
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.
<a name="project-based"></a>

[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/

<a name="pip-install"></a>
<!-- prettier-ignore-start -->

# 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:

<a name="conda-install"></a>
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

<a name="package_manager"></a>
{{< 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`.

<!-- prettier-ignore-end -->

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].

<a name="environment-based"></a>

## 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`

<!-- prettier-ignore-start -->

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

<!-- prettier-ignore-end -->

[`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/

<a name="system-package-managers"></a>

## 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

<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.
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).

0 comments on commit 4c947a9

Please sign in to comment.