Add warning for Python v3.14 (#348)

gitttt-1234 · web-flow · commit b0179afdf0f0 · 2025-10-09T10:12:10.000-07:00
This PR adds warnings to the documentation that Python 3.14 is not yet
supported and updates install instructions to pin Python (e.g., --python
3.13) when using uv so users don’t accidentally end up on 3.14. It also
updates the CI workflows to run on Python 3.13. In this PR, we also
remove the deprecated flags `--extra-index-url` and `--index-url` for
`uv`-based installations and update to `--index` flag in the
installation docs.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -27,7 +27,7 @@ jobs:
     - name: Setup UV
       uses: astral-sh/setup-uv@v6
       with:
-        python-version: "3.12"
+        python-version: "3.13"
 
     - name: Build distributions
       run: |
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -23,7 +23,7 @@ jobs:
           enable-cache: false
 
       - name: Set up Python
-        run: uv python install 3.11
+        run: uv python install 3.13
 
       - name: Install dev dependencies and torch
         run: uv sync --extra dev --extra torch-cpu
@@ -49,7 +49,7 @@ jobs:
             runs-on: macos-14
           - os: self-hosted-gpu
             runs-on: [self-hosted, puma, gpu, 2xgpu]
-        python: [3.12]
+        python: [3.13]
 
     name: Tests (${{ matrix.os }}, Python ${{ matrix.python }})
     runs-on: ${{ matrix.runs-on }}
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -28,7 +28,7 @@ jobs:
       - name: Setup UV
         uses: astral-sh/setup-uv@v6
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install dependencies
         run: |
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,6 +4,20 @@ Thank you for your interest in contributing to sleap-nn! This guide will help yo
 
 ## Development Setup
 
+> **Python 3.14 is not yet supported**
+>
+> `sleap-nn` currently supports **Python 3.11, 3.12, and 3.13**.  
+> **Python 3.14 is not yet tested or supported.**  
+> By default, `uv` will use your system-installed Python.  
+> If you have Python 3.14 installed, you must specify the Python version (≤3.13) in the install command.  
+>
+> For example:
+>
+> ```bash
+> uv sync --python 3.13 ...
+> ```
+> Replace `...` with the rest of your install command as needed.
+
 1. **Install [`uv`](https://github.com/astral-sh/uv) and development dependencies**  
    `uv` is a fast and modern package manager for `pyproject.toml`-based projects. Refer [installation docs](https://docs.astral.sh/uv/getting-started/installation/) to install uv.
 
diff --git a/README.md b/README.md
@@ -38,6 +38,20 @@ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 
 3. **Install sleap-nn dependencies based on your platform**\
 
+> **Python 3.14 is not yet supported**
+>
+> `sleap-nn` currently supports **Python 3.11, 3.12, and 3.13**.  
+> **Python 3.14 is not yet tested or supported.**  
+> By default, `uv` will use your system-installed Python.  
+> If you have Python 3.14 installed, you must specify the Python version (≤3.13) in the install command.  
+>
+> For example:
+>
+> ```bash
+> uv sync --python 3.13 ...
+> ```
+> Replace `...` with the rest of your install command as needed.
+
 - Sync all dependencies based on your correct wheel using `uv sync`. `uv sync` creates a `.venv` (virtual environment) inside your current working directory. This environment is only active within that directory and can't be directly accessed from outside. To use all installed packages, you must run commands with `uv run` (e.g., `uv run sleap-nn train ...` or `uv run pytest ...`).
    - **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
 
diff --git a/docs/index.md b/docs/index.md
@@ -43,14 +43,22 @@ We use `uvx` here which automatically installs sleap-nn from PyPI with all depen
 
 > **Quick Start Data:** Download sample training data from [here](https://storage.googleapis.com/sleap-data/datasets/BermanFlies/random_split1/train.pkg.slp) and validation data from [here](https://storage.googleapis.com/sleap-data/datasets/BermanFlies/random_split1/val.pkg.slp) for quick experimentation.
 
+!!! warning "Python 3.14 is not yet supported"
+    `sleap-nn` currently supports **Python 3.11, 3.12, and 3.13**. **Python 3.14 is not yet tested or supported.** If you have Python 3.14 installed, you must specify the Python version in the install commands by adding `--python 3.13`.  
+    For example:
+    ```bash
+    uvx --python 3.13  ...
+    ```
+    Replace `...` with the rest of your install command as needed.
+
 === "Windows/Linux (CUDA)"
     ```bash
-    uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128 sleap-nn train --config-name config.yaml --config-dir /path/to/config_dir/ "data_config.train_labels_path=[train.pkg.slp]" "data_config.val_labels_path=[val.pkg.slp]"
+    uvx --from "sleap-nn[torch]" --index https://download.pytorch.org/whl/cu128 --index https://pypi.org/simple sleap-nn train --config-name config.yaml --config-dir /path/to/config_dir/ "data_config.train_labels_path=[train.pkg.slp]" "data_config.val_labels_path=[val.pkg.slp]"
     ```
 
 === "Windows/Linux (CPU)"
     ```bash
-    uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu sleap-nn train --config-name config.yaml --config-dir /path/to/config_dir/ "data_config.train_labels_path=[train.pkg.slp]" "data_config.val_labels_path=[val.pkg.slp]"
+    uvx --from "sleap-nn[torch]" --index https://download.pytorch.org/whl/cpu --index https://pypi.org/simple sleap-nn train --config-name config.yaml --config-dir /path/to/config_dir/ "data_config.train_labels_path=[train.pkg.slp]" "data_config.val_labels_path=[val.pkg.slp]"
     ```
 
 === "macOS"
@@ -60,7 +68,7 @@ We use `uvx` here which automatically installs sleap-nn from PyPI with all depen
 
 !!! info
     - For more information on which CUDA version to use for your system, see the [PyTorch installation guide](https://pytorch.org/get-started/locally/).  
-      The `--extra-index-url` in the install command should match the CUDA version you need (e.g., `https://download.pytorch.org/whl/cuda118` for CUDA 11.8, `https://download.pytorch.org/whl/cuda128` for CUDA 12.8, etc.).
+      The `--index` in the install command should match the CUDA version you need (e.g., `https://download.pytorch.org/whl/cuda118` for CUDA 11.8, `https://download.pytorch.org/whl/cuda128` for CUDA 12.8, etc.).
     - On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.
 
 
@@ -70,12 +78,12 @@ To run inference:
 
 === "Windows/Linux (CUDA)"
     ```bash
-    uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128 sleap-nn track --data-path video.mp4 --model-paths model_ckpt_dir/
+    uvx --from "sleap-nn[torch]" --index https://download.pytorch.org/whl/cu128 --index https://pypi.org/simple sleap-nn track --data-path video.mp4 --model-paths model_ckpt_dir/
     ```
 
 === "Windows/Linux (CPU)"
     ```bash
-    uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu sleap-nn track --data-path video.mp4 --model-paths model_ckpt_dir/
+    uvx --from "sleap-nn[torch]" --index https://download.pytorch.org/whl/cpu --index https://pypi.org/simple sleap-nn track --data-path video.mp4 --model-paths model_ckpt_dir/
     ```
 
 === "macOS"
@@ -85,7 +93,7 @@ To run inference:
 
 !!! info
     - For more information on which CUDA version to use for your system, see the [PyTorch installation guide](https://pytorch.org/get-started/locally/).  
-      The `--extra-index-url` in the install command should match the CUDA version you need (e.g., `https://download.pytorch.org/whl/cuda118` for CUDA 11.8, `https://download.pytorch.org/whl/cuda128` for CUDA 12.8, etc.).
+      The `--index` in the install command should match the CUDA version you need (e.g., `https://download.pytorch.org/whl/cuda118` for CUDA 11.8, `https://download.pytorch.org/whl/cuda128` for CUDA 12.8, etc.).
     - On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.
 
 
diff --git a/docs/inference.md b/docs/inference.md
@@ -10,7 +10,7 @@ SLEAP-NN provides powerful inference capabilities for pose estimation with suppo
     
     - If you're using the `uvx` workflow, you do **not** need to install anything. (See [installation using uvx](installation.md#installation-using-uvx) for more details.)
     
-    - If you are using `uv sync` or `uv pip` installation methods, add `uv run` as a prefix to all CLI commands shown below, for example:
+    - If you are using `uv sync` or `uv add` installation methods, add `uv run` as a prefix to all CLI commands shown below, for example:
 
           `uv run sleap-nn track ...`
 
diff --git a/docs/installation.md b/docs/installation.md
@@ -2,10 +2,18 @@
 
 **Prerequisites:** Python 3.11+ (required for all installation methods)
 
+!!! warning "Python 3.14 is not yet supported"
+    `sleap-nn` currently supports **Python 3.11, 3.12, and 3.13**. **Python 3.14 is not yet tested or supported.** If you have Python 3.14 installed, you must specify the Python version in all `uv` install commands by adding `--python 3.13`.  
+    For example:
+    ```bash
+    uv tool install --python 3.13 "sleap-nn[torch]"  ...
+    ```
+    Replace `...` with the rest of your install command as needed.
+
 !!! tip "Choose Your Installation Method"
     - **[Installation as a system-wide tool with uv](#installation-as-a-system-wide-tool-with-uv)**: **(Recommended)** Use `uv tool install` to install sleap-nn globally as a CLI tool
     - **[Installation with uvx](#installation-with-uvx)**: Use `uvx` for one-off commands (no installation needed)
-    - **[Installation with uv pip](#installation-with-uv-pip)**: Use `uv pip` to install from pypi in a uv virtual env.
+    - **[Installation with uv add](#installation-with-uv-add)**: Use `uv add` to install sleap-nn as a dependency in a uv virtual env.
     - **[Installation with pip](#installation-with-pip)**: Use `pip` to install from pypi in a conda env. (Recommended to use with a conda env)
     - **[Installation from source](#installation-from-source)**: Use `uv sync` to install from source (for developmental purposes)
 
@@ -27,18 +35,26 @@
 
 ### Platform-Specific Installation
 
+!!! warning "Python 3.14 is not yet supported"
+    `sleap-nn` currently supports **Python 3.11, 3.12, and 3.13**. **Python 3.14 is not yet tested or supported.** If you have Python 3.14 installed, you must specify the Python version in the install commands by adding `--python 3.13`.  
+    For example:
+    ```bash
+    uv tool install --python 3.13 "sleap-nn[torch]"  ...
+    ```
+    Replace `...` with the rest of your install command as needed.
+
 === "Windows/Linux (CUDA)"
     ```bash
     # CUDA 12.8
-    uv tool install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128
+    uv tool install sleap-nn[torch] --index https://download.pytorch.org/whl/cu128 --index https://pypi.org/simple
 
     # CUDA 11.8
-    uv tool install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu118
+    uv tool install sleap-nn[torch] --index https://download.pytorch.org/whl/cu118 --index https://pypi.org/simple
     ```
 
 === "Windows/Linux (CPU)"
     ```bash
-    uv tool install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu
+    uv tool install sleap-nn[torch] --index https://download.pytorch.org/whl/cpu --index https://pypi.org/simple
     ```
 
 === "macOS"
@@ -48,7 +64,7 @@
 
 !!! info
     - For more information on which CUDA version to use for your system, see the [PyTorch installation guide](https://pytorch.org/get-started/locally/).  
-      The `--extra-index-url` in the install command should match the CUDA version you need (e.g., `https://download.pytorch.org/whl/cuda118` for CUDA 11.8, `https://download.pytorch.org/whl/cuda128` for CUDA 12.8, etc.).
+      The `--index` in the install command should match the CUDA version you need (e.g., `https://download.pytorch.org/whl/cuda118` for CUDA 11.8, `https://download.pytorch.org/whl/cuda128` for CUDA 12.8, etc.).
     - On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.
 
 ### Verify installation
@@ -76,16 +92,24 @@ sleap-nn --help
 
 ### Platform-Specific Commands
 
+!!! warning "Python 3.14 is not yet supported"
+    `sleap-nn` currently supports **Python 3.11, 3.12, and 3.13**. **Python 3.14 is not yet tested or supported.** If you have Python 3.14 installed, you must specify the Python version in the install commands by adding `--python 3.13`.  
+    For example:
+    ```bash
+    uvx --python 3.13  ...
+    ```
+    Replace `...` with the rest of your install command as needed.
+
 === "Windows/Linux (CUDA)"
     ```bash
-    uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128 sleap-nn train --config-name myconfig --config-dir /path/to/config_dir/
-    uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128 sleap-nn track --data_path video.mp4 --model_paths models/
+    uvx --from "sleap-nn[torch]" --index https://download.pytorch.org/whl/cu128 --index https://pypi.org/simple sleap-nn train --config-name myconfig --config-dir /path/to/config_dir/
+    uvx --from "sleap-nn[torch]" --index https://download.pytorch.org/whl/cu128 --index https://pypi.org/simple sleap-nn track --data_path video.mp4 --model_paths models/
     ```
 
 === "Windows/Linux (CPU)"
     ```bash
-    uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu sleap-nn train --config-name myconfig --config-dir /path/to/config_dir/
-    uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu sleap-nn track --data_path video.mp4 --model_paths models/
+    uvx --from "sleap-nn[torch]" --index https://download.pytorch.org/whl/cpu --index https://pypi.org/simple sleap-nn train --config-name myconfig --config-dir /path/to/config_dir/
+    uvx --from "sleap-nn[torch]" --index https://download.pytorch.org/whl/cpu --index https://pypi.org/simple sleap-nn track --data_path video.mp4 --model_paths models/
     ```
 
 === "macOS"
@@ -96,7 +120,7 @@ sleap-nn --help
 
 !!! note
     - For more information on which CUDA version to use for your system, see the [PyTorch installation guide](https://pytorch.org/get-started/locally/).  
-      The `--extra-index-url` in the install command should match the CUDA version you need (e.g., `https://download.pytorch.org/whl/cuda118` for CUDA 11.8, `https://download.pytorch.org/whl/cuda128` for CUDA 12.8, etc.).
+      The `--index` in the install command should match the CUDA version you need (e.g., `https://download.pytorch.org/whl/cuda118` for CUDA 11.8, `https://download.pytorch.org/whl/cuda128` for CUDA 12.8, etc.).
     - On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.
 
 !!! tip "How uvx Works"
@@ -110,9 +134,17 @@ sleap-nn --help
 
 ---
 
-## Installation with uv pip
+## Installation with uv add
 
-This method creates a dedicated project environment using uv's modern Python project management. It initializes a new project with `uv init`, creates an isolated virtual environment with `uv venv`, and installs sleap-nn using `uv pip`. To use all installed packages, you must run commands with `uv run` (e.g., `uv run sleap-nn train ...` or `uv run pytest ...`).
+This method creates a dedicated project environment using uv's modern Python project management. It initializes a new project with `uv init`, creates an isolated virtual environment with `uv venv`, and adds sleap-nn as a dependency using `uv add`. To use all installed packages, you must run commands with `uv run` (e.g., `uv run sleap-nn train ...` or `uv run pytest ...`).
+
+!!! warning "Python 3.14 is not yet supported"
+    `sleap-nn` currently supports **Python 3.11, 3.12, and 3.13**. **Python 3.14 is not yet tested or supported.** `uv` will use the system-installed python by default. If you have python 3.14 installed on your system, then specify the Python version (<=3.13) in the venv command.  
+    For example:
+    ```bash
+    uv venv --python 3.13  ...
+    ```
+    Replace `...` with the rest of your install command as needed.
 
 !!! note "Install and set-up uv"
     Step-1: Install [`uv`](https://github.com/astral-sh/uv) - a fast Python package manager:
@@ -132,28 +164,39 @@ This method creates a dedicated project environment using uv's modern Python pro
 
 ### Platform-Specific Installation
 
+!!! tip "How `uv add` works"
+    - When you run `uv init`, it creates a `pyproject.toml` file in your working directory to manage your project's dependencies.
+    - When you use `uv add sleap-nn[torch]`, it adds `sleap-nn[torch]` as a dependency in your `pyproject.toml` and installs it in your virtual environment.
+    - To add other packages, simply run `uv add <package>`. After adding new packages, you should run `uv sync` to update your environment with all dependencies specified in `pyproject.toml`.
+    - To install a local package (such as a local clone of sleap-nn) in editable mode, use:
+      ```bash
+      uv add --editable "./sleap-nn[torch]" ...
+      ```
+      This is useful for development, as changes to the code are immediately reflected in your environment.
+
+
 === "Windows/Linux (CUDA)"
     ```bash
     # CUDA 12.8
-    uv pip install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128
+    uv add sleap-nn[torch] ---index https://download.pytorch.org/whl/cu128 --index https://pypi.org/simple
 
     # CUDA 11.8
-    uv pip install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu118
+    uv add sleap-nn[torch] --index https://download.pytorch.org/whl/cu118 --index https://pypi.org/simple
     ```
 
 === "Windows/Linux (CPU)"
     ```bash
-    uv pip install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu
+    uv add sleap-nn[torch] --index https://download.pytorch.org/whl/cpu --index https://pypi.org/simple
     ```
 
 === "macOS"
     ```bash
-    uv pip install "sleap-nn[torch]"
+    uv add "sleap-nn[torch]"
     ```
 
 !!! info
     - For more information on which CUDA version to use for your system, see the [PyTorch installation guide](https://pytorch.org/get-started/locally/).  
-      The `--extra-index-url` in the install command should match the CUDA version you need (e.g., `https://download.pytorch.org/whl/cuda118` for CUDA 11.8, `https://download.pytorch.org/whl/cuda128` for CUDA 12.8, etc.).
+      The `--index` in the install command should match the CUDA version you need (e.g., `https://download.pytorch.org/whl/cuda118` for CUDA 11.8, `https://download.pytorch.org/whl/cuda128` for CUDA 12.8, etc.).
     - On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.
 
 ### Verify Installation
@@ -182,9 +225,12 @@ uv run sleap-nn --help
 
 We recommend creating a dedicated environment with [conda](https://docs.conda.io/en/latest/miniconda.html) or [mamba/miniforge](https://github.com/conda-forge/miniforge) before installing `sleap-nn` with pip. This helps avoid dependency conflicts and keeps your Python setup clean. After installing Miniconda or Miniforge, create and activate an environment, then run the pip install commands below inside the activated environment.
 
+!!! warning "Python 3.14 is not yet supported"
+    SLEAP currently supports **Python 3.11, 3.12, and 3.13**. **Python 3.14 is not yet tested or supported.**
+
 To create a conda environment, run:
 ```bash
-conda create -n sleap-nn-env python=3.12
+conda create -n sleap-nn-env python=3.13
 conda activate sleap-nn-env
 ```
 
@@ -255,6 +301,14 @@ cd sleap-nn
 
 #### 3. Install Dependencies
 
+!!! warning "Python 3.14 is not yet supported"
+    `sleap-nn` currently supports **Python 3.11, 3.12, and 3.13**. **Python 3.14 is not yet tested or supported.** `uv` will use the system-installed python by default. If you have python 3.14 installed on your system, then specify the Python version (<=3.13) in the installation command.  
+    For example:
+    ```bash
+    uv sync --python 3.13 ...
+    ```
+    Replace `...` with the rest of your install command as needed.
+
 === "Windows/Linux (CUDA 11.8)"
     ```bash
     uv sync --extra dev --extra torch-cuda118
diff --git a/docs/training.md b/docs/training.md
diff --git a/pyproject.toml b/pyproject.toml
