|
1 | | -### Install DeepLabCut-live on a desktop (Windows/Ubuntu) |
| 1 | +# Installation Guide |
2 | 2 |
|
3 | | -We recommend that you install DeepLabCut-live in a conda environment (It is a standard |
4 | | -python package though, and other distributions will also likely work). In this case, |
5 | | -please install [Miniconda](https://docs.anaconda.com/miniconda/miniconda-install/) |
6 | | -(recommended) or Anaconda. |
| 3 | +DeepLabCut-live can be installed using several methods. **For most users, we recommend installing from PyPI using `uv` or `pip`** - this is the simplest and most reliable method. |
7 | 4 |
|
8 | | -If you have an Nvidia GPU and want to use its capabilities, you'll need to [install CUDA |
9 | | -](https://developer.nvidia.com/cuda-downloads) first (check that CUDA is installed - |
10 | | -checkout the installation guide for [linux]( |
11 | | -https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html) or [Windows]( |
12 | | -https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/index.html). |
13 | 5 |
|
14 | | -Create a conda environment with python 3.10 or 3.11, and install |
15 | | -[`pytables`](https://www.pytables.org/usersguide/installation.html), `torch` and |
16 | | -`torchvision`. Make sure you [install the correct `torch` and `torchvision` versions |
17 | | -for your compute platform](https://pytorch.org/get-started/locally/)! |
18 | 6 |
|
19 | | -``` |
20 | | -conda create -n dlc-live python=3.11 |
21 | | -conda activate dlc-live |
22 | | -conda install -c conda-forge pytables==3.8.0 |
| 7 | +## System Requirements |
23 | 8 |
|
24 | | -# Installs PyTorch on Linux with CUDA 12.4 |
25 | | -pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124 |
26 | | -``` |
| 9 | +- Python 3.10, 3.11, or 3.12 |
| 10 | +- For GPU support: CUDA-compatible NVIDIA GPU (see [CUDA installation guide](https://developer.nvidia.com/cuda-downloads)) |
27 | 11 |
|
28 | | -Activate the conda environment, install the DeepLabCut-live package, then test the |
29 | | -installation: |
30 | 12 |
|
31 | | -``` |
32 | | -conda activate dlc-live |
33 | | -pip install deeplabcut-live |
34 | | -dlc-live-test |
35 | | -``` |
| 13 | +### Important Notes |
| 14 | + |
| 15 | +- **Required dependencies**: You must install either PyTorch or TensorFlow. Choose the one that matches your exported model: |
| 16 | + - PyTorch models: Use `deeplabcut-live[pytorch]` |
| 17 | + - TensorFlow models: Use `deeplabcut-live[tf]` |
| 18 | +- **Tensorflow support**: Tensorflow is not supported for python versions >=3.11 on Windows machines, please use python 3.10 instead. |
| 19 | +- **Conda environments**: When using `pip`, it's recommended to install in a separate conda environment to avoid dependency conflicts. |
| 20 | +- **uv sync**: If you have cloned the repository and are using `uv`, you can use `uv sync --extra pytorch` (or `--extra tf`) to install all dependencies automatically. |
| 21 | + |
| 22 | +## 1. Quick Start (recommended) |
| 23 | + |
| 24 | +Install from PyPI with PyTorch or TensorFlow: |
| 25 | + ```bash |
| 26 | + # With PyTorch (recommended) |
| 27 | + pip install deeplabcut-live[pytorch] |
| 28 | + |
| 29 | + # Or with TensorFlow |
| 30 | + pip install deeplabcut-live[tf] |
| 31 | + |
| 32 | + # Or using uv |
| 33 | + uv pip install deeplabcut-live[pytorch] # or [tf] |
| 34 | + ``` |
| 35 | + |
| 36 | +## 2. Install from Git Repository |
| 37 | +If you want to install from a local clone of the repository, follow these steps: |
| 38 | + |
| 39 | +1. Clone the repository: |
| 40 | + ```bash |
| 41 | + git clone https://github.com/DeepLabCut/DeepLabCut-live.git |
| 42 | + cd DeepLabCut-live |
| 43 | + ``` |
| 44 | + |
| 45 | +2. Install in editable mode: |
36 | 46 |
|
37 | | -Note, you can also just run the test: |
| 47 | + **Option A - with uv (recommended; fastest & dependencies are handled automatically)** |
| 48 | + ```bash |
| 49 | + # Using uv |
| 50 | + uv sync --extra pytorch --python 3.11 # or --extra tf for TensorFlow |
| 51 | + ``` |
| 52 | + |
| 53 | + **Option B - using pip in a conda environment** |
| 54 | + ``` |
| 55 | + conda create -n dlc-live python=3.11 |
| 56 | + conda activate dlc-live |
| 57 | + pip install -e ".[pytorch]" # or ".[tf]" for TensorFlow |
| 58 | + ``` |
38 | 59 |
|
39 | | -`dlc-live-test` |
| 60 | +## 3. Separate Pytorch or Tensorflow installation |
| 61 | +If the above instructions do not work, or you want to use a specific Pytorch or Tensorflow version. You can first install Pytorch or Tensorflow separately. |
| 62 | + ``` |
| 63 | + # Install Pytorch |
| 64 | + pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124 |
| 65 | + |
| 66 | + # Or install TensorFlow instead |
| 67 | + pip install tensorflow |
| 68 | + ``` |
| 69 | +and then install DeepLabCut-live following the instructions in option 1. or 2. above. |
| 70 | + |
| 71 | +## How to install uv or Conda? |
| 72 | +- **uv**: See more information on the website [here](https://docs.astral.sh/uv/#installation). The basic installation commands are: |
| 73 | + - for Linux/macOS: `curl -LsSf https://astral.sh/uv/install.sh | sh` |
| 74 | + - for Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"` |
| 75 | +- **conda**: Follow the instructions [here](https://docs.anaconda.com/miniconda/miniconda-install/). |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | + |
| 80 | +## Verify DeepLabCut-live Installation |
| 81 | + |
| 82 | +Test your installation by running: |
| 83 | + |
| 84 | +```bash |
| 85 | +dlc-live-test |
| 86 | +``` |
40 | 87 |
|
41 | 88 | If installed properly, this script will i) create a temporary folder ii) download the |
42 | 89 | full_dog model from the [DeepLabCut Model Zoo]( |
43 | 90 | http://www.mousemotorlab.org/dlc-modelzoo), iii) download a short video clip of |
44 | | -a dog, and iv) run inference while displaying keypoints. v) remove the temporary folder. |
45 | | - |
46 | | -Please note, you also should have curl installed on your computer (typically this is |
47 | | -already installed on your system), but just in case, just run `sudo apt install curl` |
| 91 | +a dog, and iv) run inference while displaying keypoints. v) remove the temporary folder. |
0 commit comments