Skip to content

Commit 02b8682

Browse files
Simplify installation guide & better highlight bundle (#814)
Note: this is a reorganization borne out of a review by Harry Barng at SciPy 2025 # Description The goal of this PR is to make the installation guide more clearly target the 3 possible user groups: experts, newcomers, and those in between. It encourages experts to just use the tools they already use, while highlighting the bundle for those who want to get started quickly. I also remove the old bundle section, since it wasn't too helpful, in favor of just directly linking to the dedicated bundle page, which is also being updated, see #813 I also change the ToC layout a bit, by nesting the Qt backends and constraints under a new heading "Advanced Installation Options".
1 parent 9b3ba83 commit 02b8682

File tree

1 file changed

+17
-32
lines changed

1 file changed

+17
-32
lines changed

docs/tutorials/fundamentals/installation.md

Lines changed: 17 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,10 @@ kernelspec:
1818

1919
This guide will teach you how to do a clean install of **napari** and launch the viewer.
2020

21-
```{note}
22-
If you want to contribute code back into napari, you should follow the [development installation instructions in the contributing guide](dev-installation) instead.
21+
If you're already familiar with Python, napari can be installed from PyPI or conda-forge using your favorite virtual environment and package manager. Otherwise, keep reading for instructions on how to install napari as a Python package.
22+
23+
```{tip}
24+
If you just want to get started quickly with napari as an app, check out our [napari app installation instructions](installation_bundle_conda.md).
2325
```
2426

2527
(install-python-package)=
@@ -30,6 +32,10 @@ This installation method allows you to use napari from Python to programmaticall
3032
interact with the app. It is the best way to install napari and make full use of
3133
all its features.
3234

35+
```{note}
36+
If you want to contribute code back into napari, you should follow the [development installation instructions in the contributing guide](dev-installation) instead.
37+
```
38+
3339
It requires:
3440
- [Python {{ python_version_range }}](https://www.python.org/downloads/)
3541
- the ability to install python packages via [pip](https://pypi.org/project/pip/) OR [conda-forge](https://conda-forge.org/docs/user/introduction.html)
@@ -39,14 +45,13 @@ You may also want:
3945
[venv](https://docs.python.org/3/library/venv.html) **(Highly recommended)**
4046

4147
```{note}
42-
New to Python or uncertain about conda, pip and virtual environments? You can use our
43-
[Bundled App](#install-as-a-bundled-app) to get started or first look at some
44-
resources we recommend:
48+
New to Python or uncertain about conda, pip, and virtual environments?
49+
Here are some resources we recommend:
4550
46-
- [Scientific Python: Getting started with Python for science](https://lectures.scientific-python.org/intro/index.html)
47-
- [Talley Lambert's Python environments workshop](https://hackmd.io/@talley/SJB_lObBi)
48-
- [Carpentries GIT workshop](https://swcarpentry.github.io/git-novice) (for those interested in contributing)
4951
52+
- [Talley Lambert's "Getting started running Python" slides](https://hms-iac.github.io/bobiac/content/02_getting_started_with_python/getting_started_with_python.html#slides)
53+
- [Scientific Python: Getting started with Python for science](https://lectures.scientific-python.org/intro/index.html)
54+
- [Detailed comparison of Python environment management tools](https://www.nijho.lt/post/python-environments/)
5055
```
5156

5257
Python package distributions of napari can be installed via `pip`, `conda-forge`, or from source.
@@ -140,8 +145,7 @@ python -m pip install "git+https://github.com/napari/napari.git#egg=napari[all]"
140145
::::::
141146

142147

143-
<!-- #region -->
144-
### Checking it worked
148+
## Checking it worked
145149

146150
After installation you should be able to launch napari from the command line by
147151
simply running
@@ -173,6 +177,8 @@ measures may further delay launches—even after the first launch.
173177
You can check the napari version, to ensure it's what you expect, for example
174178
the current release {{ napari_version }}, using the command: `napari --version` .
175179

180+
## Advanced installation options
181+
176182
### Choosing a different Qt backend
177183

178184
(choosing-qt-backend)=
@@ -188,7 +194,7 @@ running napari will result in an error message asking you to install one of
188194
them.
189195

190196
Running `python -m pip install "napari[all]"` will install the default framework, which is currently
191-
PyQt5--but this could change in the future.
197+
PyQt5--but this could change in the future.
192198

193199
To install napari with a specific framework, you can use:
194200

@@ -232,27 +238,6 @@ For example, if you would like to install napari with PyQt6 on python 3.10:
232238
pip install napari[pyqt6, optional] -c constraints_py3.10.txt
233239
```
234240

235-
## Install as a bundled app
236-
237-
napari can also be installed as a bundled app on each of the major platforms,
238-
macOS, Windows, and Linux with a simple one-click download and installation
239-
process. You might want to install napari as a bundled app if you are unfamiliar
240-
with installing Python packages or if you were unable to get the installation
241-
process described above working. The bundled app version of napari is the same
242-
version that you can get through the above described processes, and can still be
243-
extended with napari plugins installed directly via the app.
244-
245-
To access the cross platform bundles you can visit our [release
246-
page](https://github.com/napari/napari/releases) and scroll to the release you
247-
are interested in. For example, the bundles for napari {{ napari_version }} can be
248-
accessed {{ '[here](https://github.com/napari/napari/releases/tag/vNAPARI_VER)'.replace('NAPARI_VER', napari_version) }}.
249-
To get to the download link, just scroll all the way to bottom of the page and
250-
expand the `Assets` section. You can then download the appropriate file for your platform.
251-
252-
Check {doc}`installation_bundle_conda` for more detailed instructions.
253-
254-
<!-- #endregion -->
255-
256241
## Next steps
257242

258243
- to start learning how to use napari, checkout our [getting started](launch) tutorial

0 commit comments

Comments
 (0)