Skip to content

Commit ecb3673

Browse files
committed
Update readme and installation docs
- removed poetry instructions - added optional instructions for installation with uv - added notes on tensorflow support for windows
1 parent b1158f5 commit ecb3673

2 files changed

Lines changed: 94 additions & 41 deletions

File tree

README.md

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -65,20 +65,29 @@ https://www.rts.ch/play/radio/cqfd/audio/capturer-les-mouvements-des-animaux-en-
6565

6666
### Installation
6767

68-
Please see our instruction manual to install on a [Windows or Linux machine](
68+
DeepLabCut-live can be installed from PyPI with PyTorch or Tensorflow directly:
69+
```bash
70+
# With PyTorch (recommended)
71+
pip install deeplabcut-live[pytorch]
72+
73+
# Or with TensorFlow
74+
pip install deeplabcut-live[tf]
75+
76+
# Or using uv
77+
uv pip install deeplabcut-live[pytorch] # or [tf]
78+
```
79+
80+
Please see our instruction manual for more elaborate information on how to install on a [Windows or Linux machine](
6981
docs/install_desktop.md) or on a [NVIDIA Jetson Development Board](
7082
docs/install_jetson.md). Note, this code works with PyTorch, TensorFlow 1 or TensorFlow
7183
2 models, but whatever engine you exported your model with, you must import with the
7284
same version (i.e., export a PyTorch model, then install PyTorch, export with TF1.13,
7385
then use TF1.13 with DlC-Live; export with TF2.3, then use TF2.3 with DLC-live).
7486

75-
- available on pypi as: `pip install deeplabcut-live`
76-
87+
Note, you can test your installation by running:
7788

78-
Note, you can then test your installation by installing poetry (`pip install poetry`), then running:
79-
80-
```python
81-
poetry run dlc-live-test
89+
```bash
90+
dlc-live-test
8291
```
8392

8493
If installed properly, this script will i) create a temporary folder ii) download the

docs/install_desktop.md

Lines changed: 78 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,91 @@
1-
### Install DeepLabCut-live on a desktop (Windows/Ubuntu)
1+
# Installation Guide
22

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.
74

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).
135

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/)!
186

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
238

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))
2711

28-
Activate the conda environment, install the DeepLabCut-live package, then test the
29-
installation:
3012

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:
3646

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+
```
3859

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+
```
4087

4188
If installed properly, this script will i) create a temporary folder ii) download the
4289
full_dog model from the [DeepLabCut Model Zoo](
4390
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

Comments
 (0)