Skip to content

Commit ce66e07

Browse files
authored
[Doc] Update CUDA and cuDNN installation and preload (#23708)
### Description Update CUDA and cuDNN installation guide and preload configuration. ### Motivation and Context See related: #23674 #23659
1 parent 4811edb commit ce66e07

File tree

2 files changed

+110
-0
lines changed

2 files changed

+110
-0
lines changed

docs/execution-providers/CUDA-ExecutionProvider.md

+108
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ ONNX Runtime built with cuDNN 8.x is not compatible with cuDNN 9.x, and vice ver
3737

3838
Note: Starting with version 1.19, **CUDA 12.x** becomes the default version when distributing [ONNX Runtime GPU packages](https://pypi.org/project/onnxruntime-gpu/) in PyPI.
3939

40+
To reduce the need for manual installations of CUDA and cuDNN, and ensure seamless integration between ONNX Runtime and PyTorch, the `onnxruntime-gpu` Python package offers API to load CUDA and cuDNN dynamic link libraries (DLLs) appropriately. For more details, refer to the [Compatibility with PyTorch](#compatibility-with-pytorch) and [Preload DLLs](#preload-dlls) sections.
41+
4042
### CUDA 12.x
4143

4244
| ONNX Runtime | CUDA | cuDNN | Notes |
@@ -76,6 +78,112 @@ For older versions, please reference the readme and build pages on the release b
7678

7779
For build instructions, please see the [BUILD page](../build/eps.md#cuda).
7880

81+
## Compatibility with PyTorch
82+
83+
The `onnxruntime-gpu` package is designed to work seamlessly with [PyTorch](https://pytorch.org/), provided both are built against the same major version of CUDA and cuDNN. When installing PyTorch with CUDA support, the necessary CUDA and cuDNN DLLs are included, eliminating the need for separate installations of the CUDA toolkit or cuDNN.
84+
85+
To ensure ONNX Runtime utilizes the DLLs installed by PyTorch, you can preload these libraries before creating an inference session. This can be achieved by either importing PyTorch or by using the `onnxruntime.preload_dlls()` function.
86+
87+
**Example 1: Importing PyTorch**
88+
89+
```python
90+
# Import torch will preload necessary DLLs. It need to be done before creating session.
91+
import torch
92+
import onnxruntime
93+
94+
# Create an inference session with CUDA execution provider
95+
session = onnxruntime.InferenceSession("model.onnx", providers=["CUDAExecutionProvider"])
96+
```
97+
98+
99+
**Example 2: Using `preload_dlls` Function**
100+
101+
```python
102+
import onnxruntime
103+
104+
# Preload necessary DLLs
105+
onnxruntime.preload_dlls()
106+
107+
# Create an inference session with CUDA execution provider
108+
session = onnxruntime.InferenceSession("model.onnx", providers=["CUDAExecutionProvider"])
109+
```
110+
111+
## Preload DLLs
112+
113+
Since version 1.21.0, the `onnxruntime-gpu` package provides the `preload_dlls` function to preload CUDA, cuDNN, and Microsoft Visual C++ (MSVC) runtime DLLs. This function offers flexibility in specifying which libraries to load and from which directories.
114+
115+
**Function Signature:**
116+
117+
```python
118+
onnxruntime.preload_dlls(cuda=True, cudnn=True, msvc=True, directory=None)
119+
```
120+
121+
122+
**Parameters:**
123+
124+
- `cuda` (bool): Preload CUDA DLLs if set to `True`.
125+
- `cudnn` (bool): Preload cuDNN DLLs if set to `True`.
126+
- `msvc` (bool): Preload MSVC runtime DLLs if set to `True`.
127+
- `directory` (str or None): Directory to load the DLLs from.
128+
- `None`: Search in default directories.
129+
- `""` (empty string): Search in NVIDIA site packages.
130+
- Specific path: Load DLLs from the specified directory.
131+
132+
**Default Search Order:**
133+
134+
When `directory=None`, the function searches for CUDA and cuDNN DLLs in the following order:
135+
136+
1. On Windows, the `lib` directory under the PyTorch installation.
137+
2. Python site-packages directories for NVIDIA CUDA or cuDNN libraries (e.g., `nvidia_cuda_runtime_cu12`, `nvidia_cudnn_cu12`).
138+
3. Fallback to the default DLL loading behavior.
139+
140+
By preloading the necessary DLLs using default search order, you can ensure that ONNX Runtime operates seamlessly with PyTorch.
141+
142+
**Installing CUDA and cuDNN via `onnxruntime-gpu`:**
143+
144+
You can install the necessary CUDA and cuDNN runtime DLLs alongside the `onnxruntime-gpu` package using pip:
145+
146+
```bash
147+
pip install onnxruntime-gpu[cuda,cudnn]
148+
```
149+
150+
151+
**Preloading DLLs from NVIDIA Site Packages:**
152+
153+
To preload CUDA and cuDNN DLLs from NVIDIA site packages and display debug information:
154+
155+
```python
156+
import onnxruntime
157+
158+
# Preload DLLs from NVIDIA site packages
159+
onnxruntime.preload_dlls(directory="")
160+
161+
# Print debug information
162+
onnxruntime.print_debug_info()
163+
```
164+
165+
166+
**Loading DLLs from Specific Directories:**
167+
168+
To load DLLs from a specified location, set the `directory` parameter to an absolute path or a path relative to the ONNX Runtime package root.
169+
170+
**Example: Loading CUDA from System Installation and cuDNN from NVIDIA Site Package**
171+
172+
```python
173+
import os
174+
import onnxruntime
175+
176+
# Load CUDA DLLs from system installation
177+
cuda_path = os.path.join(os.environ["CUDA_PATH"], "bin")
178+
onnxruntime.preload_dlls(cuda=True, cudnn=False, directory=cuda_path)
179+
180+
# Load cuDNN DLLs from NVIDIA site package
181+
onnxruntime.preload_dlls(cuda=False, cudnn=True, directory="..\\nvidia\\cudnn\\bin")
182+
183+
# Print debug information
184+
onnxruntime.print_debug_info()
185+
```
186+
79187
## Configuration Options
80188

81189
The CUDA Execution Provider supports the following configuration options.

docs/install/index.md

+2
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ For ONNX Runtime GPU package, it is required to install [CUDA](https://developer
3838
* In Windows, the path of CUDA `bin` and cuDNN `bin` directories must be added to the `PATH` environment variable.
3939
* In Linux, the path of CUDA `lib64` and cuDNN `lib` directories must be added to the `LD_LIBRARY_PATH` environment variable.
4040

41+
For `onnxruntime-gpu` package, it is possible to work with PyTorch without the need for manual installations of CUDA or cuDNN. Refer to [Compatibility with PyTorch](../execution-providers/CUDA-ExecutionProvider.md#compatibility-with-pytorch) for more information.
42+
4143
## Python Installs
4244

4345
### Install ONNX Runtime CPU

0 commit comments

Comments
 (0)