diff --git a/docs/quickstart/installation.md b/docs/quickstart/installation.md index 267db4776..9ccc02519 100644 --- a/docs/quickstart/installation.md +++ b/docs/quickstart/installation.md @@ -1,6 +1,7 @@ # Installation ## Prerequisites + ::::::{tab-set} :::::{tab-item} Linux @@ -10,17 +11,10 @@ Install CUDA. This library has been tested with version 11.8. You can find CUDA :::::{tab-item} Windows Install [Git](https://git-scm.com/downloads). -Install CUDA. This library and the Windows installation process has been tested with version 11.7. - -::: -:::{tab-item} 11.7 with Visual Studio 2022 - Install Visual Studio 2022. This must be done before installing CUDA. The necessary components are included in the `Desktop Development with C++` workflow (also called `C++ Build Tools` in the BuildTools edition). -Install CUDA 11.7. You can find CUDA download links [here](https://developer.nvidia.com/cuda-toolkit-archive) and more information about installing CUDA [here](https://docs.nvidia.com/cuda/cuda-quick-start-guide/index.html). +Install CUDA 11.8. You can find CUDA download links [here](https://developer.nvidia.com/cuda-toolkit-archive) and more information about installing CUDA [here](https://docs.nvidia.com/cuda/cuda-quick-start-guide/index.html). -::: -:::: ::::: :::::: @@ -38,6 +32,7 @@ python -m pip install --upgrade pip ## Dependencies (pytorch)= + ### pytorch ::::{tab-set} @@ -45,11 +40,11 @@ python -m pip install --upgrade pip - To install 2.0.1 with CUDA 11.8: -Note that if a pytorch version prior to 2.0.1 is installed, -it should be uninstalled first to avoid upgrade issues (e.g. with functorch) +Note that if a pytorch version prior to 2.0.1 is installed, +the previous version of pytorch, functorch, and tiny-cuda-nn should be uninstalled. ```bash -pip uninstall torch torchvision functorch +pip uninstall torch torchvision functorch tinycudann ``` Install pytorch 2.0.1 with CUDA and [tiny-cuda-nn](https://github.com/NVlabs/tiny-cuda-nn) @@ -63,11 +58,11 @@ pip install torch==2.0.1+cu118 torchvision==0.15.2+cu118 --extra-index-url https - To install 2.0.1 with CUDA 11.7: -Note that if a pytorch version prior to 2.0.1 is installed, -it should be uninstalled first to avoid upgrade issues (e.g. with functorch) +Note that if a pytorch version prior to 2.0.1 is installed, +the previous version of pytorch, functorch, and tiny-cuda-nn should be uninstalled. ```bash -pip uninstall torch torchvision functorch +pip uninstall torch torchvision functorch tinycudann ``` Install pytorch 2.0.1 with CUDA and [tiny-cuda-nn](https://github.com/NVlabs/tiny-cuda-nn) @@ -79,9 +74,9 @@ pip install torch==2.0.1+cu117 torchvision==0.15.2+cu117 --extra-index-url https ::: :::: -### tinycudann +### tiny-cuda-nn -After pytorch and ninja, install the torch bindings for tinycudann: +After pytorch and ninja, install the torch bindings for tiny-cuda-nn: ```bash pip install ninja git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch @@ -126,14 +121,20 @@ pip install -e .[docs] ``` ## Use docker image + Instead of installing and compiling prerequisites, setting up the environment and installing dependencies, a ready to use docker image is provided. + ### Prerequisites + Docker ([get docker](https://docs.docker.com/get-docker/)) and nvidia GPU drivers ([get nvidia drivers](https://www.nvidia.de/Download/index.aspx?lang=de)), capable of working with CUDA 11.8, must be installed. The docker image can then either be pulled from [here](https://hub.docker.com/r/dromni/nerfstudio/tags) (replace with the actual version, e.g. 0.1.18) + ```bash docker pull dromni/nerfstudio: ``` + or be built from the repository using + ```bash docker build --tag nerfstudio -f Dockerfile . ``` @@ -141,12 +142,15 @@ docker build --tag nerfstudio -f Dockerfile . To restrict to only CUDA architectures that you have available locally, use the `CUDA_ARCHITECTURES` build arg and look up [the compute capability for your GPU](https://developer.nvidia.com/cuda-gpus). For example, here's how to build with support for GeForce 30xx series GPUs: + ```bash docker build --build-arg CUDA_ARCHITECTURES=86 --tag nerfstudio-86 -f Dockerfile . ``` ### Using an interactive container + The docker container can be launched with an interactive terminal where nerfstudio commands can be entered as usual. Some parameters are required and some are strongly recommended for usage as following: + ```bash docker run --gpus all \ # Give the container access to nvidia GPU (required). -v /folder/of/your/data:/workspace/ \ # Mount a folder from the local machine into the container to be able to process them (required). @@ -157,53 +161,93 @@ docker run --gpus all \ # Give the conta --shm-size=12gb \ # Increase memory assigned to container to avoid memory limitations, default is 64 MB (recommended). dromni/nerfstudio: # Docker image name if you pulled from docker hub. <--- OR ---> - nerfstudio # Docker image tag if you built the image from the Dockerfile by yourself using the command from above. + nerfstudio # Docker image tag if you built the image from the Dockerfile by yourself using the command from above. ``` + ### Call nerfstudio commands directly + Besides, the container can also directly be used by adding the nerfstudio command to the end. + ```bash docker run --gpus all -v /folder/of/your/data:/workspace/ -v /home//.cache/:/home/user/.cache/ -p 7007:7007 --rm -it --shm-size=12gb # Parameters. dromni/nerfstudio: \ # Docker image name ns-process-data video --data /workspace/video.mp4 # Smaple command of nerfstudio. ``` + ### Note + - The container works on Linux and Windows, depending on your OS some additional setup steps might be required to provide access to your GPU inside containers. -- Paths on Windows use backslash '\\' while unix based systems use a frontslash '/' for paths, where backslashes might require an escape character depending on where they are used (e.g. C:\\\\folder1\\\\folder2...). Alternatively, mounts can be quoted (e.g. ```-v 'C:\local_folder:/docker_folder'```). Ensure to use the correct paths when mounting folders or providing paths as parameters. +- Paths on Windows use backslash '\\' while unix based systems use a frontslash '/' for paths, where backslashes might require an escape character depending on where they are used (e.g. C:\\\\folder1\\\\folder2...). Alternatively, mounts can be quoted (e.g. `-v 'C:\local_folder:/docker_folder'`). Ensure to use the correct paths when mounting folders or providing paths as parameters. - Always use full paths, relative paths are known to create issues when being used in mounts into docker. - Everything inside the container, what is not in a mounted folder (workspace in the above example), will be permanently removed after destroying the container. Always do all your tasks and output folder in workdir! - The user inside the container is called 'user' and is mapped to the local user with ID 1000 (usually the first non-root user on Linux systems). - The container currently is based on nvidia/cuda:11.8.0-devel-ubuntu22.04, consequently it comes with CUDA 11.8 which must be supported by the nvidia driver. No local CUDA installation is required or will be affected by using the docker image. - The docker image (respectively Ubuntu 22.04) comes with Python3.10, no older version of Python is installed. - If you call the container with commands directly, you still might want to add the interactive terminal ('-it') flag to get live log outputs of the nerfstudio scripts. In case the container is used in an automated environment the flag should be discarded. -- The current version of docker is built for multi-architecture (CUDA architectures) use. The target architecture(s) must be defined at build time for Colmap and tinyCUDNN to be able to compile properly. If your GPU architecture is not covered by the following table you need to replace the number in the line ```ARG CUDA_ARCHITECTURES=90;89;86;80;75;70;61;52;37``` to your specific architecture. It also is a good idea to remove all architectures but yours (e.g. ```ARG CUDA_ARCHITECTURES=86```) to speedup the docker build process a lot. -- To avoid memory issues or limitations during processing, it is recommended to use either ```--shm-size=12gb``` or ```--ipc=host``` to increase the memory available to the docker container. 12gb as in the example is only a suggestion and may be replaced by other values depending on your hardware and requirements. +- The current version of docker is built for multi-architecture (CUDA architectures) use. The target architecture(s) must be defined at build time for Colmap and tinyCUDNN to be able to compile properly. If your GPU architecture is not covered by the following table you need to replace the number in the line `ARG CUDA_ARCHITECTURES=90;89;86;80;75;70;61;52;37` to your specific architecture. It also is a good idea to remove all architectures but yours (e.g. `ARG CUDA_ARCHITECTURES=86`) to speedup the docker build process a lot. +- To avoid memory issues or limitations during processing, it is recommended to use either `--shm-size=12gb` or `--ipc=host` to increase the memory available to the docker container. 12gb as in the example is only a suggestion and may be replaced by other values depending on your hardware and requirements. **Currently supported CUDA architectures in the docker image** -GPU | CUDA arch --- | -- -H100 | 90 -40X0 | 89 -30X0 | 86 -A100 | 80 -20X0 | 75 -TITAN V / V100 | 70 -10X0 / TITAN Xp | 61 -9X0 | 52 -K80 | 37 +(tiny-cuda-arch-list)= + +| GPU | CUDA arch | +| --------------- | --------- | +| H100 | 90 | +| 40X0 | 89 | +| 30X0 | 86 | +| A100 | 80 | +| 20X0 | 75 | +| TITAN V / V100 | 70 | +| 10X0 / TITAN Xp | 61 | +| 9X0 | 52 | +| K80 | 37 | ## Installation FAQ -- [TinyCUDA installation errors out with cuda mismatch](tiny-cuda-mismatch-error) -- [TinyCUDA installation errors out with no CUDA toolset found](tiny-cuda-integration-error) +- [ImportError: DLL load failed while importing \_89_C](tiny-cuda-mismatch-arch) +- [tiny-cuda-nn installation errors out with cuda mismatch](tiny-cuda-mismatch-error) +- [tiny-cuda-nn installation errors out with no CUDA toolset found](tiny-cuda-integration-error) - [Installation errors, File "setup.py" not found](pip-install-error) - [Runtime errors, "len(sources) > 0".](cuda-sources-error)
+(tiny-cuda-mismatch-arch)= + +**ImportError: DLL load failed while importing \_89_C** + +This occurs with certain GPUs that have CUDA architecture versions (89 in the example above) for which tiny-cuda-nn does not automatically compile support. + +**Solution**: + +Reinstall tiny-cuda-nn with the following command: + +::::::{tab-set} +:::::{tab-item} Linux + +```bash +TCNN_CUDA_ARCHITECTURES=XX pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch +``` + +::::: +:::::{tab-item} Windows + +```bash +set TCNN_CUDA_ARCHITECTURES=XX +pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch +``` + +::::: +:::::: + +Where XX is the architecture version listed [here](tiny-cuda-arch-list). Ie. for a 4090 GPU use `TCNN_CUDA_ARCHITECTURES=89` + +
+ (tiny-cuda-mismatch-error)= -**TinyCUDA installation errors out with cuda mismatch** +**tiny-cuda-nn installation errors out with cuda mismatch** While installing tiny-cuda, you run into: `The detected CUDA version mismatches the version that was used to compile PyTorch (10.2). Please make sure to use the same CUDA versions.` @@ -216,7 +260,7 @@ See [pytorch](pytorch) under Dependencies, above. (tiny-cuda-integration-error)= -**(Windows) TinyCUDA installation errors out with no CUDA toolset found** +**(Windows) tiny-cuda-nn installation errors out with no CUDA toolset found** While installing tiny-cuda on Windows, you run into: `No CUDA toolset found.`