Software Installation

Operating System Compatibility

Important

navigate is developed for use on Windows-based systems. This is due to the compatibility of device drivers for various microscope hardware components, such as cameras, stages, and data acquisition cards, which are predominantly designed for the Windows environment. The software is only partially tested on MacOS and Linux systems. Users considering the use of navigate software on Linux should proceed with caution and be prepared for potential compatibility issues. For optimal performance and compatibility, it is strongly recommended to run navigate on a Windows machine.

Choose an Installation Strategy

Use the table below to pick the install path that best matches your goal.

Installation Paths

Goal

Source

Environment

Recommended Path

Most users, stable release

PyPI

Conda

Conda + PyPI

Stable release without conda

PyPI

Python venv

venv + PyPI

Latest code or local development

GitHub

Conda or venv

Install from GitHub Source

Fast Python environment workflow

PyPI or GitHub

uv

uv Installation

Important

Use one environment manager per environment (for example, either Conda, venv, or uv).

Conda + PyPI

This option is recommended for most users as it provides a stable release with the benefits of Conda’s environment management. 1. Install Miniconda from the official website. 2. Open Anaconda Prompt (Miniconda3) on Windows, or a terminal on Linux/Mac. 3. Create and activate a Conda environment:

(base) conda create -n navigate python=3.9.7
(base) conda activate navigate

  1. Install the latest stable release from PyPI:

(navigate) pip install navigate-micro

venv + PyPI

  1. Navigate to the folder where you want to create the environment:

# Windows (cmd/powershell)
cd C:\path\to\your\workspace

# Linux/Mac
cd /path/to/your/workspace

  1. Create and activate a Python virtual environment:

python -m venv .venv

# Windows (cmd/powershell)
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

  1. Install from PyPI:

pip install navigate-micro

Install from GitHub

Use this path if you want the latest repository changes or intend to modify code. If you are on Windows and do not have Git installed, install Git for Windows first.

  1. Clone the repository:

git clone https://github.com/TheDeanLab/navigate.git
cd navigate

  1. Create/activate an environment (Conda or venv), then install from source:

# Non-editable install
pip install .

For development dependencies, use:

# Editable install with dev dependencies on Windows
pip install -e .[dev]

# Editable install with dev dependencies on Linux/Mac
pip install -e ".[dev]"

For full contributor setup, see Developer Install.

uv Installation (PyPI or GitHub)

If you use uv, you can manage environments and installs with the same workflow.

  1. Install uv.

  2. Create and activate an environment:

uv venv --python 3.9.7

# Windows (cmd/powershell)
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

  1. Install from PyPI:

uv pip install navigate-micro

Or install latest code directly from GitHub:

uv pip install git+https://github.com/TheDeanLab/navigate.git

Or from a local clone:

git clone https://github.com/TheDeanLab/navigate.git
cd navigate
uv pip install -e .

Once installed, you can proceed to Launching navigate to start using the software.