Skip to content

Commit 4c947a9

Browse files
lucascolleylucascolley
authored
Update installation page (#595)
1 parent 4aae151 commit 4c947a9

File tree

2 files changed

+259
-55
lines changed

2 files changed

+259
-55
lines changed

‎content/en/beginner-install.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: Beginner Installation Guide
3+
sidebar: false
4+
---
5+
6+
{{< admonition tip >}}
7+
This is the beginner installation guide.
8+
If you are comfortable with using a terminal and happy to learn
9+
how to use a package manager, check out
10+
[the main installation guide](./install.md)!
11+
{{< /admonition >}}
12+
13+
- [JupyterLite](#jupyterlite)
14+
- [Scientific Python Distributions](#distributions)
15+
- [Installing globally with `pip`](#pip-global)
16+
17+
<a name="jupyterlite"></a>
18+
19+
## JupyterLite
20+
21+
To try out SciPy, you don't even need to install it!
22+
You can use SciPy in your browser at https://jupyter.org/try-jupyter/lab/ -
23+
just open a Python Notebook, then write `import scipy` in one of
24+
the notebook "cells" and hit play.
25+
26+
For next steps, see [the SciPy user guide][scipy-user-guide].
27+
28+
[scipy-user-guide]: https://docs.scipy.org/doc/scipy/tutorial/
29+
30+
<a name="distributions"></a>
31+
32+
## Scientific Python Distributions
33+
34+
Python distributions provide the language itself, along with the most
35+
commonly used packages and tools. These downloadable files require
36+
little configuration, work on almost all setups, and provide all the
37+
most commonly used scientific Python tools.
38+
[Anaconda](https://www.anaconda.com/download/) works on Windows, Mac,
39+
and Linux, and is best suited to beginning users.
40+
Other options include:
41+
42+
- [WinPython](https://winpython.github.io): Another free distribution
43+
including scientific packages and the Spyder IDE; Windows only.
44+
- [Pyzo](https://pyzo.org): A free distribution based on Anaconda
45+
and the IEP interactive development environment; Supports Linux,
46+
Windows, and Mac.
47+
48+
{{< admonition note >}}
49+
Anaconda is free to use for inviduals, universities, and companies smaller than
50+
200 employees. For more detail, see Anaconda's helpful blog on
51+
["when is Anaconda free to use?"](https://www.anaconda.com/blog/update-on-anacondas-terms-of-service-for-academia-and-research)
52+
{{< /admonition >}}
53+
54+
After installing a scientific Python distribution,
55+
see next steps in [the SciPy user guide][scipy-user-guide].
56+
57+
<a name="pip-global"></a>
58+
59+
## Installing globally with `pip`
60+
61+
If you already have Python installed, you can install SciPy
62+
with `pip` by executing the following in a terminal/shell:
63+
64+
python -m pip install scipy
65+
66+
{{< admonition warning >}}
67+
You may see this recommended in tutorials or classes, but the recommended
68+
way to install SciPy with `pip` is to use a virtual environment -
69+
see [Installing with `pip`](./install.md#installing-with-pip).
70+
{{< /admonition >}}
71+
72+
{{< admonition note >}}
73+
For more information on why this is not a recommended installation method,
74+
read about [virtual environments in the Python Packaging User Guide](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments).
75+
{{< /admonition >}}

‎content/en/install.md

Lines changed: 184 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -3,101 +3,230 @@ title: Installation
33
sidebar: false
44
---
55

6-
Installations methods include:
6+
{{< admonition tip >}}
7+
This page assumes that you are comfortable with using a terminal and happy to learn
8+
how to use a package manager. If you are a beginner and just want to get started
9+
with SciPy as quickly as possible, check out
10+
[the beginner installation guide](./beginner-install.md)!
11+
{{< /admonition >}}
712

8-
- [Distributions](#distributions)
9-
- [pip](#pip-install)
10-
- [conda](#pip-install)
11-
- [Package Manager](#package_manager)
12-
- [Source](#source)
13+
The recommended method of installing SciPy depends on your preferred workflow.
14+
The common workflows can roughly be broken down into the following
15+
categories:
1316

14-
Methods differ in ease of use, coverage, maintenance of old versions,
15-
system-wide versus local environment use, and control. With pip or
16-
Anaconda\'s conda, you can control the package versions for a specific
17-
project to prevent conflicts. Conda also controls non-Python packages,
18-
like MKL or HDF5. System package managers, like `apt-get`, install
19-
across the entire computer, often have older versions, and don\'t have
20-
as many available versions. Source compilation is much more difficult
21-
but is necessary for debugging and development. If you don\'t know which
22-
installation method you need or prefer, we recommend the Scientific
23-
Python Distribution [Anaconda](https://www.anaconda.com/download/).
17+
- [Project-based (e.g. `uv`, `pixi`)](#project-based) (recommended for new users)
18+
- [Environment-based (e.g. `pip`, `conda`)](#environment-based) (the traditional workflow)
19+
- [System package managers](#system-package-managers) (not recommended)
20+
- [Building from source](#building-from-source) (for debugging and development)
2421

25-
<a name="distributions"></a>
22+
To install SciPy with [static type stubs],
23+
see [Installing with type stubs](#type-stubs).
2624

27-
# Scientific Python Distributions (recommended)
25+
[static type stubs]: https://typing.readthedocs.io/en/latest/guides/libraries.html
2826

29-
Python distributions provide the language itself, along with the most
30-
commonly used packages and tools. These downloadable files require
31-
little configuration, work on almost all setups, and provide all the
32-
commonly used scientific Python tools.
27+
<a name="project-based"></a>
3328

34-
[Anaconda](https://www.anaconda.com/download/) works on Windows, Mac,
35-
and Linux, provides over 1,500 Python packages, and is used by over 15
36-
million people. Anaconda is best suited to beginning users; it provides
37-
a large collection of libraries all in one.
29+
## Project-based workflows
3830

39-
For more advanced users who will need to install or upgrade regularly,
40-
[Mambaforge](https://github.com/conda-forge/miniforge#mambaforge) is a more
41-
suitable way to install the `conda` (and `mamba`, a faster `conda` alternative)
42-
package manager.
31+
### Installing with `uv`
4332

44-
Other options include:
33+
Here is a step-by-step guide to setting up a project to use SciPy, with [`uv`],
34+
a Python package manager.
4535

46-
- [WinPython](https://winpython.github.io): Another free distribution
47-
including scientific packages and the Spyder IDE; Windows only, but
48-
more actively maintained and supports the latest Python 3 versions.
49-
- [Pyzo](https://pyzo.org): A free distribution based on Anaconda
50-
and the IEP interactive development environment; Supports Linux,
51-
Windows, and Mac.
36+
[`uv`]: https://docs.astral.sh/uv/
5237

53-
<a name="pip-install"></a>
38+
<!-- prettier-ignore-start -->
5439

55-
# Installing with Pip
40+
1. Install `uv`, following [the instructions in the `uv` documentation][install-uv].
5641

57-
You can install SciPy from PyPI with `pip`:
42+
[install-uv]: https://docs.astral.sh/uv/getting-started/installation/
5843

59-
python -m pip install scipy
44+
2. Create a new project in a new subdirectory, by executing the following in a terminal:
6045

61-
<a name="conda-install"></a>
46+
uv init try-scipy
47+
cd try-scipy
6248

63-
# Installing via Conda
49+
{{< admonition hint >}}
50+
The second command changes directory into the directory of your project.
51+
{{< /admonition >}}
6452

65-
You can install SciPy from the `defaults` or `conda-forge` channels with `conda`:
53+
3. Add SciPy to your project:
6654

67-
conda install scipy
55+
uv add scipy
6856

69-
<a name="package_manager"></a>
57+
{{< admonition note >}}
58+
This will automatically install Python if you don't already have it installed!
59+
{{< /admonition >}}
7060

71-
# Install system-wide via a package manager
61+
{{< admonition tip >}}
62+
You can install other Python libraries in the same way, e.g.
63+
64+
uv add matplotlib
65+
66+
{{< /admonition >}}
67+
68+
4. Try out SciPy!
69+
70+
uv run python
71+
72+
This will launch a Python interpreter session, from which you can `import scipy`.
73+
74+
<!-- prettier-ignore-end -->
75+
76+
See next steps in [the SciPy user guide][scipy-user-guide].
77+
78+
[scipy-user-guide]: https://docs.scipy.org/doc/scipy/tutorial/
79+
80+
{{< admonition note >}}
81+
82+
After rebooting your computer, you'll want to navigate to your `try-scipy`
83+
project directory and execute `uv run python` to drop back into a Python interpreter
84+
with SciPy importable.
85+
To execute a Python script, you can use `uv run myscript.py`.
86+
87+
Read more at [the uv guide to working on projects][uv-projects].
88+
89+
[uv-projects]: https://docs.astral.sh/uv/guides/projects/
90+
91+
{{< /admonition >}}
92+
93+
### Installing with `pixi`
94+
95+
If you work with non-Python packages, you may prefer to install SciPy as
96+
a [Conda] package, so that you can use the same workflow for packages which
97+
are not available on [PyPI](https://pypi.org/), the Python Package Index.
98+
Conda can manage packages in any language, so you can use it to install
99+
Python itself, compilers, and other languages.
100+
101+
[Conda]: https://docs.conda.io/projects/conda/en/latest/index.html
102+
103+
The steps to install SciPy from [conda-forge] using the package management
104+
tool [`pixi`] are very similar to the steps for `uv`:
105+
106+
[conda-forge]: https://conda-forge.org/
107+
[`pixi`]: https://pixi.sh/latest/
108+
109+
1. Install `pixi`, following [the instructions in the `pixi` documentation][install-pixi].
110+
111+
[install-pixi]: https://pixi.sh/latest/
112+
113+
2. Create a new project in a new subdirectory:
114+
115+
pixi init try-scipy
116+
cd try-scipy
117+
118+
3. Add SciPy to your project:
119+
120+
pixi add scipy
121+
122+
4. Try out SciPy!
123+
124+
pixi run python
125+
126+
See next steps in [the SciPy user guide][scipy-user-guide].
127+
128+
<a name="environment-based"></a>
129+
130+
## Environment-based workflows
131+
132+
In project-based workflows, a project is a directory containing a manifest
133+
file describing the project, a lock-file describing the exact dependencies
134+
of the project, and the project's (potentially multiple) environments.
135+
136+
In contrast,
137+
in environment-based workflows you install packages into an environment,
138+
which you can activate and deactivate from any directory.
139+
These workflows are well-established,
140+
but lack some reproducibility benefits of project-based workflows.
141+
142+
### Installing with `pip`
143+
144+
<!-- prettier-ignore-start -->
145+
146+
1. [Install Python](https://www.python.org/downloads/).
147+
148+
2. Create and activate a virtual environment with `venv`.
149+
150+
{{< admonition hint >}}
151+
See [the tutorial in the Python Packaging User Guide](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments).
152+
{{< /admonition >}}
153+
154+
3. Install SciPy, using [`pip`]:
155+
156+
python -m pip install scipy
157+
158+
<!-- prettier-ignore-end -->
159+
160+
[`pip`]: https://pip.pypa.io/en/stable/getting-started/
161+
162+
### Installing with `conda`
163+
164+
[Miniforge] is the recommended way to install `conda` and [`mamba`],
165+
two Conda-based environment managers.
166+
After creating an environment, you can install SciPy from conda-forge as follows:
167+
168+
conda install scipy # or
169+
mamba install scipy
170+
171+
[Miniforge]: https://conda-forge.org/download/
172+
[`mamba`]: https://mamba.readthedocs.io/en/latest/
173+
174+
<a name="system-package-managers"></a>
175+
176+
## Installing system-wide via a system package manager
72177

73178
System package managers can install the most common Python packages.
74179
They install packages for the entire computer, often use older versions,
75-
and don't have as many available versions.
180+
and don't have as many available versions. They are not the recommended
181+
installation method.
76182

77-
## Ubuntu and Debian
183+
### Ubuntu and Debian
78184

79185
Using `apt-get`:
80186

81187
sudo apt-get install python3-scipy
82188

83-
## Fedora
189+
### Fedora
84190

85191
Using `dnf`:
86192

87193
sudo dnf install python3-scipy
88194

89-
## macOS
195+
### macOS
90196

91197
macOS doesn't have a preinstalled package manager, but you can install
92198
[Homebrew](https://brew.sh/) and use it to install SciPy (and Python itself):
93199

94200
brew install scipy
95201

96-
<a name="source"></a>
202+
<a name="building-from-source"></a>
97203

98-
# Source packages
204+
## Building from source
99205

100206
A word of warning: building SciPy from source can be a nontrivial exercise. We
101-
recommend using binaries instead if those are available for your platform.
207+
recommend using binaries instead if those are available for your platform
208+
via one of the above methods.
102209
For details on how to build from source, see
103-
[this guide in the SciPy docs](https://scipy.github.io/devdocs/building/index.html).
210+
[the building from source guide in the SciPy docs][building-docs].
211+
212+
[building-docs]: https://scipy.github.io/devdocs/building/index.html
213+
214+
<a name="type-stubs"></a>
215+
216+
## Installing with type stubs
217+
218+
Static type stubs are available via a separate package, `scipy-stubs`, on
219+
PyPI and conda-forge.
220+
You can also install SciPy and `scipy-stubs` as a single package,
221+
via the `scipy-stubs[scipy]` extra on PyPI, or the `scipy-typed`
222+
package on conda-forge.
223+
To get a specific version `x.y.z` of SciPy (such as `1.14.1`),
224+
you should install version `x.y.z.*`, for example:
225+
226+
uv add "scipy-stubs[scipy]==1.14.1.*" # or
227+
pixi add "scipy-typed=1.15.0.*" # or
228+
python -m pip install "scipy-stubs[scipy]" # or
229+
conda install "scipy-typed>=1.14"
230+
231+
Please direct questions about static typing support to
232+
[the `scipy-stubs` GitHub repository](https://github.com/jorenham/scipy-stubs).

0 commit comments

Comments
 (0)