From c78dba8c7219f360fe55fcd341bac8b234607994 Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Fri, 10 Oct 2025 18:42:11 +0100
Subject: [PATCH 01/11] add uv lock to gitignore

---
 .gitignore | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.gitignore b/.gitignore
index 6611c73ad..61a9573fc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -92,3 +92,6 @@ venv/
 
 # pre-commit and pytest cache
 .*_cache/
+
+# uv related
+uv.lock

From 9b297793f4955de1e06e52cae19d5243e763d914 Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Fri, 10 Oct 2025 18:42:49 +0100
Subject: [PATCH 02/11] pull tables from pypi instead of conda-forge

---
 pyproject.toml | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 0087ab1ea..578c3427b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -17,6 +17,7 @@ dependencies = [
   "pandas",
   "h5py",
   "netCDF4<1.7.3",
+  "tables>=3.10.1",
   "attrs",
   "pooch",
   "tqdm",
@@ -156,7 +157,7 @@ check-hidden = true
 legacy_tox_ini = """
 [tox]
 requires =
-    tox-conda
+    tox>=4
     tox-gh-actions
 envlist = py{311,312,313}
 isolated_build = True
@@ -168,10 +169,6 @@ python =
     3.13: py313
 
 [testenv]
-conda_deps =
-    pytables
-conda_channels =
-    conda-forge
 passenv =
     CI
     GITHUB_ACTIONS

From 41d5dedc5a2f43cfbc6bc190edc0ad4853acc233 Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Fri, 10 Oct 2025 18:57:03 +0100
Subject: [PATCH 03/11] remove tables drom docs requirements.txt

---
 docs/requirements.txt | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 384ed256e..58e492c45 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -11,4 +11,3 @@ sphinx-design
 sphinx-gallery
 sphinx-notfound-page
 sphinx-sitemap
-tables

From ac4dbe7192cab1c8da38497d1a58d6e3b865482e Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Mon, 20 Oct 2025 18:55:33 +0100
Subject: [PATCH 04/11] updated installation guide

---
 docs/source/conf.py                    |   1 +
 docs/source/user_guide/installation.md | 170 +++++++++++++++++--------
 2 files changed, 118 insertions(+), 53 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 5da9273e0..aa6a6995c 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -220,6 +220,7 @@
     "via": "https://www.robots.ox.ac.uk/~vgg/software/via/{{path}}#{{fragment}}",
     "anipose": "https://anipose.readthedocs.io/en/latest/",
     "TRex": "https://trex.run/docs/",
+    "uv": "https://docs.astral.sh/uv/{{path}}#{{fragment}}",
 }
 
 intersphinx_mapping = {
diff --git a/docs/source/user_guide/installation.md b/docs/source/user_guide/installation.md
index 6907eeedc..26e99c530 100644
--- a/docs/source/user_guide/installation.md
+++ b/docs/source/user_guide/installation.md
@@ -1,79 +1,115 @@
 (target-installation)=
 # Installation
 
-## Install the package
-:::{admonition} Use a conda environment
-:class: note
-To avoid dependency conflicts with other packages, it is best practice to install Python packages within a virtual environment.
-We recommend using [conda](conda:) or [mamba](mamba:) to create and manage this environment, as they simplify the installation process.
-The following instructions assume that you have conda installed, but the same commands will also work with `mamba`/`micromamba`.
-:::
+## Use a virtual environment
 
-### Users
-To install movement in a new environment, follow one of the options below.
-We will use `movement-env` as the environment name, but you can choose any name you prefer.
+While not strictly required, it is highly recommended to install `movement` into a
+clean virtual environment, using tools such as [conda](conda:) or [uv](uv:).
+
+This should be set up before installing `movement`.
 
 ::::{tab-set}
-:::{tab-item} Conda
-To create an environment with the core package only:
+:::{tab-item} conda
+Create and activate a new environment:
 ```sh
-conda create -n movement-env -c conda-forge movement
+conda create -y -n movement-env -c conda-forge python=3.13
+conda activate movement-env
 ```
 
-If you wish to use the GUI, which additionally requires [napari](napari:),
-you should instead run:
+We used `movement-env` as the environment name, but you can choose any name you prefer.
+:::
+
+:::{tab-item} uv
+Make sure [uv is installed on your system](uv:getting-started/installation).
+Then create a [virtual environment](uv:pip/environments/) in your project directory:
+
 ```sh
-conda create -n movement-env -c conda-forge movement napari pyqt
+uv init
+uv venv --python=3.13
 ```
-You may exchange `pyqt` for `pyside2` if you prefer.
-See [napari's installation guide](napari:tutorials/fundamentals/installation.html)
-for more information on the backends.
 
-To activate the environment:
-```sh
-conda activate movement-env
+Activate the virtual environment:
+```bash
+source .venv/bin/activate  # On macOS and Linux
+```
+```powershell
+.venv\Scripts\activate     # On Windows PowerShell
 ```
 :::
+::::
+
+## Install the package
+With your environment activated, install `movement` using one of the methods below.
 
-:::{tab-item} Pip
-Create and activate an environment with some prerequisites:
+::::{tab-set}
+:::{tab-item} From conda-forge using conda
+To install the core package:
 ```sh
-conda create -n movement-env -c conda-forge python=3.12 pytables
-conda activate movement-env
+conda install -c conda-forge movement
 ```
-Install the core package from the latest release on PyPI:
+
+If you wish to use the GUI, which requires [napari](napari:), run instead:
+```sh
+conda install -c conda-forge movement napari pyqt
+```
+You may exchange `pyqt` for `pyside6` if you prefer a different Qt backend.
+See [napari's installation guide](napari:tutorials/fundamentals/installation.html)
+for more details on available backends.
+
+:::
+
+:::{tab-item} From PyPI using pip
+Install the core package:
 ```sh
 pip install movement
 ```
-If you wish to use the GUI, which additionally requires [napari](napari:),
-you should instead run:
+If you wish to use the GUI, which requires [napari](napari:), run instead:
 ```sh
-pip install movement[napari]   # works on most shells
-pip install 'movement[napari]' # works on zsh (default shell on macOS)
+pip install "movement[napari]"
 ```
 :::
+
+:::{tab-item} From PyPI using uv
+Install the core package:
+```sh
+uv pip install movement
+```
+If you wish to use the GUI, which requires [napari](napari:), run instead:
+```sh
+uv pip install "movement[napari]"
+```
+:::
+
 ::::
 
 :::{dropdown} Note for Apple Silicon users with macOS 13 or earlier
 :color: info
 :icon: info
 
-We recommend installing `movement` following the `Conda` instructions above, as the `pip` method will likely fail for you.
-Alternatively, updating your macOS to version 14 or later will allow `pip` installations to work as expected.
+If you are running macOS 13 or earlier on Apple Silicon (M-series) hardware,
+we recommend installing `movement` via `conda-forge`,
+which provides pre-built Qt libraries compatible with macOS 13.
+Alternatively, upgrading to macOS 14 or later enables installation via `pip` or `uv`
+without compatibility issues.
+
 :::
 
-### Developers
-If you are a developer looking to contribute to movement, please refer to our [contributing guide](target-contributing) for detailed setup instructions and guidelines.
+:::{admonition} For developers
+:class: tip
+
+If you plan to contribute to `movement`, see the [contributing guide](target-contributing)
+for detailed developer setup instructions and coding guidelines.
+:::
 
-## Check the installation
-To verify that the installation was successful, run (with `movement-env` activated):
+## Verify the installation
+With your virtual environment activated, run:
 ```sh
 movement info
 ```
-You should see a printout including the version numbers of movement
+You should see a printout including the version numbers of `movement`
 and some of its dependencies.
 
-To test the GUI installation, you can run:
+To test the GUI installation:
 
 ```sh
 movement launch
@@ -83,37 +119,65 @@ This is equivalent to running `napari -w movement` and should open the `napari`
 window with the `movement` widget docked on the right-hand side.
 
 ## Update the package
-To update `movement` to the latest version, you need to use the same package manager you used to install it (either `conda` or `pip`). If you are not sure which one you used, you can run from your active environment:
+
+Always update using the same package manager you used for installation.
+
+If you are not sure which one you used, you can run `conda list movement` from your active `conda` environment
+and check whether the output shows `conda-forge` or `pypi` as the channel.
+
+To update `movement`, run the appropriate command below:
+
+::::{tab-set}
+:::{tab-item} conda
 ```sh
-conda list movement
+conda update -c conda-forge movement -y
 ```
-If the output shows `conda-forge` as the channel, you used `conda` to install it. If it shows `pypi`, you used `pip`.
+:::
 
-Once this is clear, you can update `movement` by running the relevant command from below:
-::::{tab-set}
-:::{tab-item} Conda
+:::{tab-item} pip
 ```sh
-conda update movement -y
+pip install -U movement
 ```
 :::
 
-:::{tab-item} Pip
+:::{tab-item} uv
 ```sh
-pip install movement -U
+uv pip install -U movement
 ```
 :::
 ::::
 
 
-If the above fails, try installing it in a fresh new environment instead. This should prevent potential compatibility issues caused by changes in dependency versions. You can first uninstall the existing environment named `movement-env`:
+If the above fails, try installing `movement` in a fresh new environment to avoid dependency conflicts.
+
+First remove the existing environment:
+
+::::{tab-set}
+:::{tab-item} conda
 ```sh
 conda env remove -n movement-env
 ```
-Once the environment has been removed, you can create a new one following the [installation instructions](#install-the-package) above.
 
-:::{tip}
-If you are unsure about the environment name, you can get a list of the environments on your system with:
+This command assumes your environment is named `movement-env`.
+If you are unsure about the name, you can get a list of the environments
+on your system with `conda env list`.
+:::
+
+:::{tab-item} uv
+Simply delete the `.venv` folder in your project directory.
+
+```bash
+rm -rf .venv       # On macOS and Linux
+```
+```powershell
+rmdir /s /q .venv  # On Windows PowerShell
+```
+
+Optionally, you may also clean the `uv` cache for unused packages:
 ```sh
-conda env list
+uv cache prune
 ```
 :::
+::::
+
+Once the environment has been removed, you can create a new one following the [instructions](#use-a-virtual-environment) above.

From 7152e66984a77ca8f0e52824cff0188b3594ab8b Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Sat, 25 Oct 2025 22:27:44 +0100
Subject: [PATCH 05/11] Disable HDF5 file locking in tox

---
 pyproject.toml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/pyproject.toml b/pyproject.toml
index 578c3427b..53a0af587 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -176,6 +176,8 @@ passenv =
     XAUTHORITY
     NUMPY_EXPERIMENTAL_ARRAY_FUNCTION
     PYVISTA_OFF_SCREEN
+setenv =
+    HDF5_USE_FILE_LOCKING = FALSE
 extras =
     dev
 commands =

From 5783acb70c9713238d31742162bd50d3a088d3ed Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Sat, 25 Oct 2025 22:59:46 +0100
Subject: [PATCH 06/11] Revert "Disable HDF5 file locking in tox"

This reverts commit 8173f323eef96417fe0dc641ebf93d638d9fc984.
---
 pyproject.toml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 53a0af587..578c3427b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -176,8 +176,6 @@ passenv =
     XAUTHORITY
     NUMPY_EXPERIMENTAL_ARRAY_FUNCTION
     PYVISTA_OFF_SCREEN
-setenv =
-    HDF5_USE_FILE_LOCKING = FALSE
 extras =
     dev
 commands =

From 4e88f91b5b294bcd77845a239ac8bae6c2459302 Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Wed, 29 Oct 2025 19:49:53 +0000
Subject: [PATCH 07/11] updated instruction for creating a dev environment

---
 CONTRIBUTING.md                        | 77 ++++++++++++++++++--------
 docs/source/user_guide/installation.md |  4 +-
 2 files changed, 56 insertions(+), 25 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4f3360195..e5bd39ed7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -25,36 +25,67 @@ These are especially suitable if you're new to the project, and we recommend sta
 
 ## Contributing code
 
-
 ### Creating a development environment
-It is recommended to use [conda](conda:)
-or [mamba](mamba:) to create a
-development environment for `movement`. In the following we assume you have
-`conda` installed, but the same commands will also work with `mamba`/`micromamba`.
 
-First, create and activate a `conda` environment with some prerequisites:
+In order to make changes to `movement`, you will need to fork the [repository](movement-github:).
+If you are not familiar with `git`, we recommend reading up on [this guide](https://docs.github.com/en/get-started/using-git/about-git#basic-git-commands).
 
-```sh
-conda create -n movement-dev -c conda-forge python=3.13 pytables
-conda activate movement-dev
-```
+1. Clone the forked repository to your local machine and change directories:
 
-To install `movement` for development, clone the [GitHub repository](movement-github:),
-and then run from within the repository:
+    ```sh
+    git clone https://github.com/neuroinformatics-unit/movement.git
+    cd movement
+    ```
 
-```sh
-pip install -e .[dev]  # works on most shells
-pip install -e '.[dev]'  # works on zsh (the default shell on macOS)
-```
+2. Set the upstream remote to the base `movement` repository:
 
-This will install the package in editable mode, including all dependencies
-required for development.
+    ```sh
+    git remote add upstream https://github.com/neuroinformatics-unit/movement.git
+    ```
 
-Finally, initialise the [pre-commit hooks](#formatting-and-pre-commit-hooks):
+3. Create an environment using [conda](conda:) or [uv](uv:) and install `movement` in editable mode, including development dependencies.
 
-```bash
-pre-commit install
-```
+    ::::{tab-set}
+
+    :::{tab-item} conda
+    First, create and activate a `conda` environment:
+
+    ```sh
+    conda create -n movement-dev -c conda-forge python=3.13
+    conda activate movement-dev
+    ```
+
+    Then, install the package in editable mode with development dependencies:
+
+    ```sh
+    pip install -e ".[dev]"
+    ```
+    :::
+
+    :::{tab-item} uv
+
+    First, create and activate a [virtual environment](uv:pip/environments/):
+
+    ```sh
+    uv venv --python=3.13
+    source .venv/bin/activate  # On macOS and Linux
+    .venv\Scripts\activate     # On Windows PowerShell
+    ```
+
+    Then, install the package in editable mode with development dependencies:
+
+    ```sh
+    uv pip install -e ".[dev]"
+    ```
+    :::
+
+    ::::
+
+4. Finally, initialise the [pre-commit hooks](#formatting-and-pre-commit-hooks):
+
+    ```sh
+    pre-commit install
+    ```
 
 ### Pull requests
 In all cases, please submit code to the main repository via a pull request (PR).
@@ -218,6 +249,8 @@ To edit the documentation, first clone the repository, and install `movement` in
 Then, install a few additional dependencies in your development environment to be able to build the documentation locally. To do this, run the following command from the root of the repository:
 ```sh
 pip install -r ./docs/requirements.txt
+# or, for uv users:
+uv pip install -r ./docs/requirements.txt
 ```
 
 Now create a new branch, edit the documentation source files (`.md` or `.rst` in the `docs` folder),
diff --git a/docs/source/user_guide/installation.md b/docs/source/user_guide/installation.md
index 26e99c530..7fea443d9 100644
--- a/docs/source/user_guide/installation.md
+++ b/docs/source/user_guide/installation.md
@@ -29,10 +29,8 @@ uv venv --python=3.13
 ```
 
 Activate the virtual environment:
-```bash
+```sh
 source .venv/bin/activate  # On macOS and Linux
-```
-```powershell
 .venv\Scripts\activate     # On Windows PowerShell
 ```
 :::

From 310c2bb1ebd5c23418d0a272abdd43fcf37e249e Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Wed, 29 Oct 2025 19:51:56 +0000
Subject: [PATCH 08/11] remove mamba link from url scheme

---
 docs/source/conf.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index aa6a6995c..73ec6ade6 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -207,7 +207,6 @@
     "dlc": "https://www.mackenziemathislab.org/deeplabcut/",
     "gin": "https://gin.g-node.org/{{path}}#{{fragment}}",
     "github-docs": "https://docs.github.com/en/{{path}}#{{fragment}}",
-    "mamba": "https://mamba.readthedocs.io/en/latest/",
     "myst-parser": "https://myst-parser.readthedocs.io/en/latest/{{path}}#{{fragment}}",
     "napari": "https://napari.org/dev/{{path}}",
     "setuptools-scm": "https://setuptools-scm.readthedocs.io/en/latest/{{path}}#{{fragment}}",

From a46140e21aa26add5d02cf9b1bf922a7d1a6e2cb Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Fri, 7 Nov 2025 10:25:09 +0000
Subject: [PATCH 09/11] Revert "linkcheck ignore BraiAn"

This reverts commit 7e5a7e0d4230b6a2c942656b51446117b06e0d7f.
---
 docs/source/conf.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 73ec6ade6..ac6965fe6 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -191,7 +191,6 @@
     "https://opensource.org/license/bsd-3-clause/",  # to avoid odd 403 error
     "https://www.sainsburywellcome.org/",  # Occasional ConnectTimeoutError
     "https://www.robots.ox.ac.uk/",  # occasional 404s
-    "https://silvalab.codeberg.page/BraiAn/",  # SSLError despite working link
 ]
 
 

From 049c1076f07d90a3cc35a906afcb558391789773 Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Fri, 7 Nov 2025 13:45:09 +0000
Subject: [PATCH 10/11] Implement suggestions from PR review

---
 CONTRIBUTING.md                        | 16 ++++----
 docs/source/conf.py                    |  2 +-
 docs/source/user_guide/installation.md | 51 ++++++++++++--------------
 3 files changed, 32 insertions(+), 37 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e5bd39ed7..e7947b856 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -30,10 +30,10 @@ These are especially suitable if you're new to the project, and we recommend sta
 In order to make changes to `movement`, you will need to fork the [repository](movement-github:).
 If you are not familiar with `git`, we recommend reading up on [this guide](https://docs.github.com/en/get-started/using-git/about-git#basic-git-commands).
 
-1. Clone the forked repository to your local machine and change directories:
+1. Clone the forked repository to your local machine and change directory:
 
     ```sh
-    git clone https://github.com/neuroinformatics-unit/movement.git
+    git clone https://github.com/<your-github-username>/movement.git
     cd movement
     ```
 
@@ -43,7 +43,7 @@ If you are not familiar with `git`, we recommend reading up on [this guide](http
     git remote add upstream https://github.com/neuroinformatics-unit/movement.git
     ```
 
-3. Create an environment using [conda](conda:) or [uv](uv:) and install `movement` in editable mode, including development dependencies.
+3. Create an environment using [conda](conda:) or [uv](uv:getting-started/installation/) and install `movement` in editable mode, including development dependencies.
 
     ::::{tab-set}
 
@@ -243,14 +243,12 @@ The deployment job runs on tag pushes (for PyPI releases) or manual triggers on
 This keeps the documentation aligned with releases, while allowing manual redeployment when necessary.
 
 ### Editing the documentation
-To edit the documentation, first clone the repository, and install `movement` in a
-[development environment](#creating-a-development-environment).
+To edit the documentation, ensure you have already set up a [development environment](#creating-a-development-environment).
 
-Then, install a few additional dependencies in your development environment to be able to build the documentation locally. To do this, run the following command from the root of the repository:
+To build the documentation locally, install the extra dependencies by running the following command from the repository root:
 ```sh
-pip install -r ./docs/requirements.txt
-# or, for uv users:
-uv pip install -r ./docs/requirements.txt
+pip install -r ./docs/requirements.txt      # conda env
+uv pip install -r ./docs/requirements.txt   # uv env
 ```
 
 Now create a new branch, edit the documentation source files (`.md` or `.rst` in the `docs` folder),
diff --git a/docs/source/conf.py b/docs/source/conf.py
index ac6965fe6..5200f332b 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -202,7 +202,7 @@
     "movement-github": "https://github.com/neuroinformatics-unit/movement/{{path}}",
     "movement-zulip": "https://neuroinformatics.zulipchat.com/#narrow/stream/406001-Movement",
     "movement-community-calls": "https://neuroinformatics.zulipchat.com/#narrow/channel/406001-Movement/topic/Community.20Calls",
-    "conda": "https://docs.conda.io/en/latest/",
+    "conda": "https://docs.conda.io/projects/conda/en/latest/{{path}}#{{fragment}}",
     "dlc": "https://www.mackenziemathislab.org/deeplabcut/",
     "gin": "https://gin.g-node.org/{{path}}#{{fragment}}",
     "github-docs": "https://docs.github.com/en/{{path}}#{{fragment}}",
diff --git a/docs/source/user_guide/installation.md b/docs/source/user_guide/installation.md
index 7fea443d9..8d12162b8 100644
--- a/docs/source/user_guide/installation.md
+++ b/docs/source/user_guide/installation.md
@@ -1,16 +1,15 @@
 (target-installation)=
 # Installation
 
-## Use a virtual environment
+## Create a virtual environment
 
-While not strictly required, it is highly recommended to install `movement` into a
-clean virtual environment, using tools such as [conda](conda:) or [uv](uv:).
-
-This should be set up before installing `movement`.
+While not strictly required, we strongly recommended installing `movement` in a
+clean virtual environment, using tools such as
+[conda](conda:) or [uv](uv:getting-started/installation/).
 
 ::::{tab-set}
 :::{tab-item} conda
-Create and activate a new environment:
+Create and activate a new [conda environment](conda:user-guide/tasks/manage-environments.html):
 ```sh
 conda create -y -n movement-env -c conda-forge python=3.13
 conda activate movement-env
@@ -20,11 +19,9 @@ We used `movement-env` as the environment name, but you can choose any name you
 :::
 
 :::{tab-item} uv
-Make sure [uv is installed on your system](uv:getting-started/installation).
-Then create a [virtual environment](uv:pip/environments/) in your project directory:
+Create and activate a new [virtual environment](uv:pip/environments/) inside your project directory:
 
 ```sh
-uv init
 uv venv --python=3.13
 ```
 
@@ -41,7 +38,7 @@ With your environment activated, install `movement` using one of the methods bel
 
 ::::{tab-set}
 :::{tab-item} From conda-forge using conda
-To install the core package:
+Install the core package:
 ```sh
 conda install -c conda-forge movement
 ```
@@ -84,18 +81,15 @@ uv pip install "movement[napari]"
 :color: info
 :icon: info
 
-If you are running macOS 13 or earlier on Apple Silicon (M-series) hardware,
-we recommend installing `movement` via `conda-forge`,
-which provides pre-built Qt libraries compatible with macOS 13.
-Alternatively, upgrading to macOS 14 or later enables installation via `pip` or `uv`
-without compatibility issues.
-
+If you are using macOS 13 or earlier on Apple Silicon (M-series),
+we recommend installing `movement` via `conda-forge`.
+Alternatively, upgrade to macOS 14 to use any of the installation methods above.
 :::
 
 :::{admonition} For developers
 :class: tip
 
-If you plan to contribute to `movement`, see the [contributing guide](target-contributing)
+If you would like to contribute to `movement`, see our [contributing guide](target-contributing)
 for detailed developer setup instructions and coding guidelines.
 :::
 
@@ -118,12 +112,17 @@ window with the `movement` widget docked on the right-hand side.
 
 ## Update the package
 
-Always update using the same package manager you used for installation.
+:::{dropdown} Always update using the same package manager used for installation
+:icon: info
+:color: info
+
+If your environment was created with `conda`, first check which channel `movement` was installed from before updating.
+Run `conda list movement` in your active `conda` environment and look at the **Channel** column:
+- If the channel is `conda-forge`, update using `conda`.
+- If the channel is `pypi`, update using `pip`.
 
-If you are not sure which one you used, you can run `conda list movement` from your active `conda` environment
-and check whether the output shows `conda-forge` or `pypi` as the channel.
+:::
 
-To update `movement`, run the appropriate command below:
 
 ::::{tab-set}
 :::{tab-item} conda
@@ -162,20 +161,18 @@ on your system with `conda env list`.
 :::
 
 :::{tab-item} uv
-Simply delete the `.venv` folder in your project directory.
+Delete the `.venv` folder in your project directory.
 
-```bash
-rm -rf .venv       # On macOS and Linux
-```
 ```powershell
+rm -rf .venv       # On macOS and Linux
 rmdir /s /q .venv  # On Windows PowerShell
 ```
 
-Optionally, you may also clean the `uv` cache for unused packages:
+Optionally, you can clean the `uv` cache for unused packages:
 ```sh
 uv cache prune
 ```
 :::
 ::::
 
-Once the environment has been removed, you can create a new one following the [instructions](#use-a-virtual-environment) above.
+Once the environment has been removed, you can create a new one following the [instructions](#create-a-virtual-environment) above.

From 8c89d54f294807899ba7e82682c4fbc250e118df Mon Sep 17 00:00:00 2001
From: niksirbi <niko.sirbiladze@gmail.com>
Date: Fri, 7 Nov 2025 14:08:01 +0000
Subject: [PATCH 11/11] tweak wording in uv venv instructions

---
 docs/source/user_guide/installation.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/source/user_guide/installation.md b/docs/source/user_guide/installation.md
index 8d12162b8..95fd4eef8 100644
--- a/docs/source/user_guide/installation.md
+++ b/docs/source/user_guide/installation.md
@@ -23,10 +23,7 @@ Create and activate a new [virtual environment](uv:pip/environments/) inside you
 
 ```sh
 uv venv --python=3.13
-```
 
-Activate the virtual environment:
-```sh
 source .venv/bin/activate  # On macOS and Linux
 .venv\Scripts\activate     # On Windows PowerShell
 ```