Skip to content

Update installation instructions #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TimMonko wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Update installation instructions #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3b8e964
update install instructions
TimMonko Nov 26, 2025
8bf1064
drop tox
TimMonko Nov 28, 2025
3399adc
update mkdocs config for mkdocstrings-python 2.0.0
TimMonko Nov 28, 2025
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
127 changes: 89 additions & 38 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,105 +2,156 @@

If you are unfamiliar with python or the command line, instead use the bundled app installer as demonstrated in [Beginner Setup](beginner_setup.md).

## Install with uv
## Install with uv (Recommended)

uv is the newest and fastest way to manage python libraries. It is very easy to install, and simplifies environment manage, but requires some minimal input to the command line. [Install uv from here](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_1). Then, the simplest way to install `napari-ndev`:
[uv](https://docs.astral.sh/uv/) is the newest and fastest way to manage Python libraries. It's easy to install and simplifies environment management. [Install uv here](https://docs.astral.sh/uv/getting-started/installation/).

```bash
uv tool install napari-ndev[qtpy-backend]
```

Alternatively, download the full opinionated package, which includes non-BSD3 licensed libraries with:
Recommended: Install napari-ndev as a uv tool, with optional dependencies including sample data, themes, and additional plugins:

```bash
uv tool install napari-ndev[all]
```

Then, you can easily open napari with the command line every time by just typing:
Then launch napari with the nDev App widget open:

```bash
napari-ndev
napari -w napari-ndev "nDev App"
```

The tool version of `napari-ndev` effectively runs as an alias for `napari -w napari-ndev` and opens the `nDev App` upon launch. With this method, additional plugins installed via the plugin menu persist between each call to `napari-ndev`
This is equivalent to `napari -w napari-ndev "nDev App"`. Additional plugins installed via napari's plugin menu persist between sessions.

To update a tool with uv:
To update:

```bash
uv tool upgrade napari-ndev
```

## Install with pip

**napari-ndev** is a pure Python package, and can be installed with [pip] (and it is recommended to do so in a [managed environment](https://biapol.github.io/blog/mara_lampert/getting_started_with_mambaforge_and_python/readme.html)):
Alternatively, create a dedicated virtual environment:

```bash
pip install napari-ndev
uv venv
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

uv pip install napari-ndev[all]
```

If napari is currently not installed in your environment, you will also need to include a QtPy backend:
## Install with pip

**napari-ndev** is a pure Python package and can be installed with [pip] (recommended in a [managed environment](https://biapol.github.io/blog/mara_lampert/getting_started_with_mambaforge_and_python/readme.html)):

```bash
pip install napari-ndev[qtpy-backend]
```

The easiest way to get started with **napari-ndev** is to install all the optional dependencies (see note below) with:
This installs napari-ndev with napari and PyQt6 (the Qt backend).

The easiest way to get started is to install all optional dependencies:

```bash
pip install napari-ndev[all]
```

Afterwards, you can call from the command line (in the same environment) `napari-ndev` to open napari with the `nDev App` open on launch.
After installation, launch napari with the nDev App widget open:

```bash
napari-ndev
```

### Optional Dependencies

**napari-ndev** provides several optional dependency groups:

### Optional Libraries
- **`[qtpy-backend]`** - Includes `napari[pyqt6]` for the Qt GUI
- **`[extras]`** - Additional napari plugins (napari-assistant, simpleitk-image-processing, segment-blobs-and-things-with-membranes)
- **`[all]`** - Everything above plus ndev-sampledata and ndev-themes (recommended for most users)

**napari-ndev** is most useful when interacting with some other napari plugins (e.g. napari-assistant) and can read additional filetypes. A few extra BSD3 compatible napari-plugins may be installed with [pip]:
Install specific groups as needed:

```bash
pip install napari-ndev[extras]
pip install napari-ndev[extras] # Just additional plugins
```

**napari-ndev** can optionally use GPL-3 licensed libraries to enhance its functionality, but are not required. If you choose to install and use these optional dependencies, you must comply with the GPL-3 license terms. The main functional improvement is from some `bioio` libraries to support extra image formats, including `czi` and `lif` files. These libraries can be installed with [pip]:
### Additional Image Format Support

**napari-ndev** uses [ndevio](https://github.com/ndev-kit/ndevio) for image I/O, which relies on [bioio](https://github.com/bioio-devs/bioio) readers. Basic formats (TIFF, OME-TIFF, OME-Zarr, PNG, JPEG) work out of the box.

For additional proprietary formats, install the appropriate bioio reader:

```bash
pip install napari-ndev[gpl-extras]
# CZI files (GPL-3 licensed)
pip install bioio-czi

# LIF files (GPL-3 licensed)
pip install bioio-lif

# Bio-Formats for many formats (functionality not guaranteed)
pip install bioio-bioformats
```

In addition, you may need to install specific [`bioio` readers](https://github.com/bioio-devs/bioio) to support your specific image, such as `bioio-czi` and `bioio-lif` (included in `[gpl-extras]`) or `bioio-bioformats` (which needs conda installed).
**License Note:** Some bioio readers (like bioio-czi and bioio-lif) are GPL-3 licensed. If you install and use these, you must comply with GPL-3 license terms. See the [bioio documentation](https://bioio-devs.github.io/bioio/) for the full list of available readers.

## Development Libraries
## Install with Pixi (For Development)

For development use the `[dev]` optional libraries to verify your changes, which includes the `[docs]` and `[testing]` optional groups. However, the Github-CI will test pull requests with `[testing]` only.
[Pixi](https://pixi.sh) provides reproducible, cross-platform environments and is excellent for development.

### Development with uv
Clone the repository and use Pixi:

```bash
git clone https://github.com/ndev-kit/napari-ndev.git
cd napari-ndev
```

uv can be a useful tool for building as similar an environment as possible across systems. To do so, navigate in your terminal to the `napari-ndev` source directory. `--python` sets the minimum python version. `--no-workspace` prevents discovering parent workspaces. Then:
Launch napari with the nDev App:

```bash
uv init --python 3.11 --no-workspace
uv sync
pixi run napari-ndev
```

You may use uv to set a certain python version, e.g.:
Or install in editable mode and activate the environment:

```bash
uv pin python 3.11
pixi install # Default environment with qtpy-backend
pixi install -e dev # Development environment with testing tools

pixi shell # Activate the environment
napari # Run napari or any command
```

To use uv to install extras (like with `napari-ndev[dev]`), use:
Run tests:

```bash
uv sync --extra dev
pixi run -e dev test
```

You may also test the tool version of uv during development with:
The `pixi.toml` defines several environments:

- `default` - Minimal installation with qtpy-backend
- `all` - All optional dependencies
- `extras` - Additional napari plugins only
- `dev` - Development environment with testing tools (pytest, ruff, pre-commit)

### Development with uv

For development with uv, clone the repository and create a virtual environment:

```bash
uv install tool .
git clone https://github.com/ndev-kit/napari-ndev.git
cd napari-ndev

uv venv -p 3.13
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

uv pip install -e . --group dev
```

You can also test with tox in parallel ([via tox-uv](https://github.com/tox-dev/tox-uv)) with:
Run tests:

```bash
tox - p auto
uv run pytest -v
```
6 changes: 1 addition & 5 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,11 +112,7 @@ plugins:
- mkdocstrings:
handlers:
python:
import:
- https://docs.python.org/3/objects.inv
- https://psygnal.readthedocs.io/en/latest/objects.inv
- https://pint.readthedocs.io/en/stable/objects.inv
- https://napari.org/stable/objects.inv
paths: [.]
options:
docstring_style: numpy # required
heading_level: 2
Expand Down