Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/developers/contributing/dev_install.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ In order to make changes to `napari`, you will need to [fork](https://docs.githu
pip install -e ".[pyqt]" --group dev # (quotes only needed for zsh shell)
```

To use PySide2 instead of the PyQt5, use:
To use PySide6 instead of the PyQt5, use:

```sh
pip install -e ".[pyside]" --group dev # (quotes only needed for zsh shell)
Expand Down
2 changes: 1 addition & 1 deletion docs/developers/coredev/packaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ extra_envs:
- napari=1.2.3
- napari-menu=1.2.3
- python # pinned to a specific version, configured by CI
- pyside2 # pinned to a specific version, configured by CI
- pyside6 # pinned to a specific version, configured by CI
- conda # needed for the plugin manager
- mamba # needed for the plugin manager
- pip # needed for the plugin manager
Expand Down
2 changes: 1 addition & 1 deletion docs/developers/coredev/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ and run the command from the second line of a given constraints file.
For example:

```bash
uv pip compile --python-version 3.12 --output-file resources/constraints/constraints_py3.12.txt pyproject.toml resources/constraints/version_denylist.txt --extra pyqt6 --extra pyside2 --extra pyside6_experimental --extra testing --extra testing_extra --extra optional
uv pip compile --python-version 3.12 --output-file resources/constraints/constraints_py3.12.txt pyproject.toml resources/constraints/version_denylist.txt --extra pyqt6 --extra pyside6 --extra testing --extra testing_extra --extra optional
```
````

Expand Down
13 changes: 6 additions & 7 deletions docs/plugins/building_a_plugin/best_practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,15 @@ affect the ability to install or use your plugin effectively.

(best-practices-no-qt-backend)=

## Don't include `napari[all]`, `PySide2`, `PyQt5` or `PyQt6` in your plugin's default dependencies.
## Don't include `napari[all]`, `PySide6`, `PyQt5` or `PyQt6` in your plugin's default dependencies.

*This is important! Avoid including any form of Qt in your plugin's dependencies!*

Napari supports *both* PyQt and PySide backends for Qt. It is up to the
end-user to choose which one they want. If they installed napari with `pip install napari[all]`, then this includes `PyQt5` from PyPI as the default backend.
If they installed via `conda install napari pyqt`, then they'll have `PyQt5`,
but from conda-forge instead of PyPI. Meanwhile, the napari bundle installs with PySide2.
Users are also free to install PyQt6, which is fully supported, or the
experimental PySide6 backend.
but from conda-forge instead of PyPI. Meanwhile, the napari bundle installs with PySide6.
Users are also free to install PyQt6, or PySide6 backend.

Here's what can go wrong if you *also* declare one of these backends **or napari[all]**
in the `dependencies`/`install_requires` section of your plugin metadata:
Expand All @@ -29,7 +28,7 @@ in the `dependencies`/`install_requires` section of your plugin metadata:
environment and re-install napari*. This is an unfortunate consequence of
[package naming decisions](https://github.com/ContinuumIO/anaconda-issues/issues/1554),
and it's not something napari can fix.
- Alternatively, they may end up with some combination of *both* PyQt5, PyQt6, PySide2,
- Alternatively, they may end up with some combination of *both* PyQt5, PyQt6,
and PySide6 in their environment: the Qt backend they had installed and the one your
plugin installed as a dependency. This is will not *always* to break things, but
it will lead to unexpected and difficult to debug problems.
Expand Down Expand Up @@ -59,10 +58,10 @@ command line installation in a fresh environment. In `pyproject.toml` this would

````

## Don't import from any specific Qt backend (e.g. PyQt5, PySide2, etc.) in your plugin: use `qtpy`
## Don't import from any specific Qt backend (e.g. `PyQt5`, `PyQt6`, `PySide6`, etc.) in your plugin: use `qtpy`

If you use `from PyQt5 import QtCore` (or similar) in your plugin, but the
end-user has chosen to use `PySide2` for their Qt backend — or vice versa —
end-user has chosen to use `PySide6` or `PyQt6` for their Qt backend — or vice versa —
then your plugin will fail to import. Instead use `from qtpy import QtCore`.
`qtpy` is a [Qt compatibility layer](https://github.com/spyder-ide/qtpy)
that will import from whatever backend is installed in the environment.
Expand Down
3 changes: 1 addition & 2 deletions docs/tutorials/fundamentals/getting_started.md
Original file line number Diff line number Diff line change
Expand Up @@ -230,7 +230,7 @@ First you need to validate if you have Qt bindings installed. You can do this by
pip list
```

And check if `PyQt5`, `PySide2`, `PyQt6` or `PySide6` are mentioned in the output as installed.
And check if `PyQt5`, `PyQt6` or `PySide6` are mentioned in the output as installed.

If there is no such entry, please install one of them following the instructions
in [Choosing a different Qt backend](choosing-qt-backend)
Expand All @@ -255,7 +255,6 @@ Such import may look like **one** of the following lines:
```python
from PyQt5 import QtWidgets
from PyQt6 import QtWidgets
from PySide2 import QtWidgets
from PySide6 import QtWidgets
```

Expand Down
24 changes: 11 additions & 13 deletions docs/tutorials/fundamentals/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,10 +89,10 @@ You can then upgrade to a new version of napari using:
conda update napari
```

If you want to install napari with PySide2 as the backend you need to install it using
If you want to install napari with PySide6 as the backend you need to install it using

```sh
conda install -c conda-forge napari pyside2
conda install -c conda-forge napari pyside6
```

````{note}
Expand Down Expand Up @@ -186,9 +186,9 @@ the current release {{ napari_version }}, using the command: `napari --version`
(choosing-qt-backend)=

napari needs a library called [Qt](https://www.qt.io/) to run its user interface
(UI). In Python, there are two alternative libraries to run this, called
[PyQt5](https://www.riverbankcomputing.com/software/pyqt/download) and
[PySide2](https://doc.qt.io/qtforpython-6/). By default, we don't choose for you,
(UI). In Python, there are three alternative libraries to run this, called
[PyQt5](https://www.riverbankcomputing.com/software/pyqt/download) for Qt5,
[PyQt5](https://www.riverbankcomputing.com/software/pyqt/download) and [PySide6](https://doc.qt.io/qtforpython-6/) for Qt6. By default, we don't choose for you,
and simply running `python -m pip install napari` will not install either. You *might*
already have one of them installed in your environment, thanks to other
scientific packages such as Spyder or matplotlib. If neither is available,
Expand All @@ -204,23 +204,21 @@ To install napari with a specific framework, you can use:
python -m pip install "napari[pyqt6, optional]" # for PyQt6

# OR
python -m pip install "napari[pyside2, optional]" # for PySide2
python -m pip install "napari[pyside6, optional]" # for PySide6
```

By including `optional` you will install everything that `napari[all]` includes, but with the Qt backend of your choice.

Please note that, if you have a Mac with the newer arm64
architecture ([Apple Silicon](https://support.apple.com/en-us/116943)), then installing the PySide2 backend using `pip` is not supported because pre-compiled PySide2 packages
([wheels](https://realpython.com/python-wheels/)) are not available on
[PyPI](https://pypi.org), the repository used by `pip`. However,
you can install `pyside2` separately, for example from `conda-forge`,
and then use `pip install napari`.

```{note}
If you switch backends, it's a good idea to `pip uninstall` the one
you're not using.
```

```{note}
As PySide2 is not maintained, we drop support for it in napari 0.7.0.
PyQt5 is still supported, as there is no PyQt6 on conda-forge yet.
```

### Using constraints files

Since napari 0.4.18, we store constraints files with information about each exact dependency version against which napari was tested.
Expand Down