Skip to content

Commit 45d18dc

Browse files
Add troubleshooting page (#533)
# References and relevant issues Closes #40, #493 # Description Adds a troubleshooting page under Usage. Not complete by any means, but a starting point. It has two sections, one for known issues and another for an FAQ. --------- Co-authored-by: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com>
1 parent 6376ddb commit 45d18dc

3 files changed

Lines changed: 48 additions & 0 deletions

File tree

docs/_toc.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ subtrees:
7474
- file: further-resources/glossary
7575
- file: further-resources/napari-workshops
7676
- file: further-resources/sample_data
77+
- file: troubleshooting
7778
- file: gallery
7879
- file: release/index
7980
subtrees:

docs/howtos/layers/image.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -349,6 +349,7 @@ we had passed only the colormap it would have been given a default name.
349349
The named colormap now appears in the dropdown alongside a thumbnail of the full
350350
range of the colormap.
351351

352+
(contrast-limits)=
352353
## Adjusting contrast limits
353354

354355
Each image layer gets mapped through its colormap according to values called

docs/troubleshooting.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Troubleshooting
2+
3+
This page collects a few known issues and solutions for common problems that users might encounter when using napari.
4+
If you are facing an error that is not covered by this page, please check existing issues on the
5+
[napari repository](https://github.com/napari/napari/issues). If you can't find what you are looking for,
6+
please open a new issue.
7+
8+
## Known issues
9+
10+
### Resetting preferences and settings
11+
12+
Changing napari versions—updating or downgrading—within an environment can cause issues with settings. These issues can
13+
manifest as napari failing to start.
14+
15+
Likewise, issues with napari on multiple monitors or with window sizes are also due to settings. These issues can
16+
frequently be solved by resetting the settings back to default using the terminal command:
17+
18+
```python
19+
napari --reset
20+
```
21+
22+
### torch + rosetta + napari crashes Python
23+
24+
In some cases, when using napari on Mac M1 using Rosetta you may experience crashing when adding layers or using a script.
25+
If you observe this, you should run napari using the native arm64 Python interpreter (see [napari#7259](https://github.com/napari/napari/issues/7259).
26+
27+
### "module napari has no attribute Viewer"
28+
29+
This may happen when doing an editable install on top of a normal one, or when you have a local file called `napari.py`.
30+
31+
To fix this, either rename the file or remove all previous napari versions in your environment before installing the editable version.
32+
33+
### My image renders as all black/all white
34+
35+
This can happen when the contrast limits are not set correctly. You can reset the contrast limits by right-clicking
36+
"contrast limits", then clicking the "Reset" button in the advanced contrast limits widget shown.
37+
38+
See [](contrast-limits) for more information on contrast limits.
39+
40+
### PermissionError when trying to launch napari on Windows
41+
42+
If you have a PermissionError when trying to launch napari on Windows, it could be due to how numba deals with
43+
permissions. Try setting `NUMBA_CACHE_DIR` to an user-accessible location.
44+
45+
See [napari#7288](https://github.com/napari/napari/issues/7288).
46+

0 commit comments

Comments
 (0)