Skip to content

Commit 90bbe27

Browse files
committed
Rework installation instructions
1 parent 66ad118 commit 90bbe27

1 file changed

Lines changed: 60 additions & 78 deletions

File tree

README.md

Lines changed: 60 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -99,18 +99,12 @@ ffmpeg -f lavfi -i \
9999
```
100100

101101
## Installing TorchCodec
102-
### Installing CPU-only TorchCodec
103102

104-
1. Install the latest stable version of PyTorch following the
105-
[official instructions](https://pytorch.org/get-started/locally/). For other
106-
versions, refer to the table below for compatibility between versions of
107-
`torch` and `torchcodec`.
108-
109-
2. Install FFmpeg, if it's not already installed. TorchCodec supports
110-
all major FFmpeg versions in [4, 8].
111-
Linux distributions usually come with FFmpeg pre-installed. You'll need
112-
FFmpeg that comes with separate shared libraries. This is especially relevant
113-
for Windows users: these are usually called the "shared" releases.
103+
1. Install FFmpeg, if it's not already installed. TorchCodec supports all major
104+
FFmpeg versions in [4, 8]. Linux distributions usually come with FFmpeg
105+
pre-installed. You'll need FFmpeg that comes with separate shared libraries.
106+
This is especially relevant for Windows users: these are usually called the
107+
"shared" releases.
114108

115109
If FFmpeg is not already installed, or you need a more recent version, an
116110
easy way to install it is to use `conda`:
@@ -121,12 +115,65 @@ ffmpeg -f lavfi -i \
121115
conda install "ffmpeg" -c conda-forge
122116
```
123117

124-
3. Install TorchCodec:
118+
2. Install PyTorch and TorchCodec:
125119

126120
```bash
127-
pip install torchcodec --index-url=https://download.pytorch.org/whl/cpu
121+
pip install torch torchcodec
128122
```
129123

124+
That's it! On Linux and Windows, this will install CUDA-enabled wheels by
125+
default (matching the default behavior of `pip install torch`). These wheels
126+
should *still* work even if you do not have a GPU on your machine. On macOS,
127+
this will install CPU-only wheels. CPU wheels are available for Linux (x86_64
128+
and aarch64), macOS, and Windows.
129+
130+
For other versions of PyTorch, refer to the compatibility table below.
131+
132+
### CUDA support
133+
134+
CUDA-enabled wheels are installed by default on Linux and Windows (see above).
135+
Make sure you have a GPU with NVDEC hardware that can decode the format you
136+
want. Refer to Nvidia's GPU support matrix
137+
[here](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new).
138+
139+
You will need the `libnpp` and `libnvrtc` CUDA libraries, which are usually
140+
part of the CUDA Toolkit.
141+
142+
To select a specific CUDA Toolkit version, use `--index-url`. Make sure to
143+
install the corresponding PyTorch version as well (refer to the
144+
[official instructions](https://pytorch.org/get-started/locally/)):
145+
146+
```bash
147+
# This corresponds to CUDA Toolkit version 13.0.
148+
pip install torch torchcodec --index-url=https://download.pytorch.org/whl/cu130
149+
```
150+
151+
Make sure your FFmpeg has NVDEC support:
152+
153+
```bash
154+
ffmpeg -decoders | grep -i nvidia
155+
# This should show a line like this:
156+
# V..... h264_cuvid Nvidia CUVID H264 decoder (codec h264)
157+
```
158+
159+
To check that FFmpeg libraries work with NVDEC correctly you can decode a
160+
generated test video:
161+
162+
```bash
163+
ffmpeg -hwaccel cuda -hwaccel_output_format cuda -f lavfi -i testsrc2=duration=1 -f null -
164+
```
165+
166+
### CPU-only installation
167+
168+
To install CPU-only wheels explicitly (e.g. on Linux where CUDA wheels are the
169+
default):
170+
171+
```bash
172+
pip install torchcodec --index-url=https://download.pytorch.org/whl/cpu
173+
```
174+
175+
### Compatibility
176+
130177
The following table indicates the compatibility between versions of
131178
`torchcodec`, `torch` and Python.
132179

@@ -155,71 +202,6 @@ The following table indicates the compatibility between versions of
155202

156203
</details>
157204

158-
### Installing CUDA-enabled TorchCodec
159-
160-
First, make sure you have a GPU that has NVDEC hardware that can decode the
161-
format you want. Refer to Nvidia's GPU support matrix for more details
162-
[here](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new).
163-
164-
1. Install FFmpeg with NVDEC support.
165-
TorchCodec with CUDA should work with FFmpeg versions in [4, 8].
166-
167-
If FFmpeg is not already installed, or you need a more recent version, an
168-
easy way to install it is to use `conda`:
169-
170-
```bash
171-
conda install "ffmpeg"
172-
# or
173-
conda install "ffmpeg" -c conda-forge
174-
```
175-
176-
After installing FFmpeg make sure it has NVDEC support when you list the supported
177-
decoders:
178-
179-
```bash
180-
ffmpeg -decoders | grep -i nvidia
181-
# This should show a line like this:
182-
# V..... h264_cuvid Nvidia CUVID H264 decoder (codec h264)
183-
```
184-
185-
To check that FFmpeg libraries work with NVDEC correctly you can decode a sample video:
186-
187-
```bash
188-
ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i test/resources/nasa_13013.mp4 -f null -
189-
```
190-
191-
#### Linux
192-
193-
2. Install Pytorch corresponding to your CUDA Toolkit using the
194-
[official instructions](https://pytorch.org/get-started/locally/). You'll
195-
need the `libnpp` and `libnvrtc` CUDA libraries, which are usually part of
196-
the CUDA Toolkit.
197-
198-
3. Install TorchCodec
199-
200-
On Linux, `pip install torchcodec` defaults to a CUDA wheel,
201-
matching the default behavior of `pip install torch`.
202-
203-
```bash
204-
pip install torchcodec
205-
```
206-
Use `--index-url` to select a different CUDA Toolkit version:
207-
208-
```bash
209-
# This corresponds to CUDA Toolkit version 13.0. It should be the same one
210-
# you used when you installed PyTorch (If you installed PyTorch with pip).
211-
pip install torchcodec --index-url=https://download.pytorch.org/whl/cu130
212-
```
213-
214-
#### Windows
215-
216-
2. On Windows (experimental support), you'll need to rely on `conda` to install
217-
both pytorch and TorchCodec:
218-
219-
```bash
220-
conda install -c conda-forge "torchcodec=*=*cuda*"
221-
```
222-
223205
## Benchmark Results
224206

225207
The following was generated by running [our benchmark script](./benchmarks/decoders/generate_readme_data.py) on a lightly loaded 22-core machine with an Nvidia A100 with

0 commit comments

Comments
 (0)