Install Nerfstudio v1.1.5: NeRF Open Source Guide

Why does every NeRF open source install stall on tiny-cuda-nn, even when the README looks fine? If you’ve already burned an afternoon on CUDA mismatch errors, you’re not alone – and you don’t need another “what is a radiance field” lecture.

Nerfstudio v1.1.5 (GitHub release, 11 Nov 2024) is the modular studio most people mean when they search for NeRF open source tooling that can train, view, and export without a research lab’s glue scripts. It sits behind the ns-* CLI. The design paper is arXiv:2302.04264 (Berkeley BAIR lineage). This guide pins v1.1.5, leads with Docker, and only covers failure modes that show up in official docs and real install threads.

System requirements before you touch pip

Miss the GPU/CUDA pair and you’ll compile for twenty minutes, then fail at import. Numbers below track official install notes and the nerfacto method page (as of docs.nerf.studio; recheck before a new GPU purchase).

The project README is blunt: tested with CUDA 11.8, NVIDIA GPU required. No GPU means you’re off the supported path. CPU-only is not what they ship.

Where to get Nerfstudio v1.1.5

Stay on first-party channels: GitHub nerfstudio-project/nerfstudio (see also the v1.1.5 release notes), PyPI via pip install nerfstudio, and ghcr.io/nerfstudio-project/nerfstudio (latest or a fixed tag). Install steps live at docs.nerf.studio/installation. Skip random mirrors as your root of trust.

Pick an install path (then stick to it)

Three supported routes. Pain levels are not the same.

Docker path (fastest clean deploy)

You need Docker, a host driver that can run CUDA 11.8 containers, and the NVIDIA Container Toolkit so --gpus all actually works.

docker pull ghcr.io/nerfstudio-project/nerfstudio:latest
# Prefer a fixed tag when you need bit-for-bit repeatability (docs examples use tags like :1.1.3)

docker run --gpus all 
 -u $(id -u) 
 -v /absolute/path/to/your/data:/workspace/ 
 -v $HOME/.cache/:/home/user/.cache/ 
 -p 7007:7007 
 --rm -it 
 --shm-size=12gb 
 ghcr.io/nerfstudio-project/nerfstudio:latest

--shm-size=12gb is load-bearing. Official Docker notes call out the default 64 MB shared memory as enough to OOM or wedge data processing under real jobs – --ipc=host is the other documented escape hatch. Mount absolute host paths; relative mounts fail in practice. Anything not on a volume vanishes when the container exits.

Native conda + pip (Linux preferred)

conda create --name nerfstudio -y python=3.8
conda activate nerfstudio
python -m pip install --upgrade pip

pip install torch==2.1.2+cu118 torchvision==0.16.2+cu118 
 --extra-index-url https://download.pytorch.org/whl/cu118
conda install -c "nvidia/label/cuda-11.8.0" cuda-toolkit

pip install ninja git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch
pip install nerfstudio
# optional:
ns-install-cli

Order matters. A bare pip install nerfstudio on a messy env is a known way to land CPU torch or to fight a CUDA torch you already spent an hour pinning – community reports and the official sequence both point the same way: install torch==2.1.2+cu118 (and matching torchvision) before tiny-cuda-nn and the nerfstudio package. If junk is already present: pip uninstall torch torchvision functorch tinycudann, then redo the cu118 wheel.

Pinned source tree for the release tag:

git clone https://github.com/nerfstudio-project/nerfstudio.git
cd nerfstudio
git checkout tags/v1.1.5
pip install --upgrade pip setuptools
pip install -e .

Pro tip: On Windows, install Visual Studio 2022 Desktop Development with C++ before CUDA tooling, run vcvars64.bat in that shell, and treat activation as session-only. Close the terminal and the build env is gone – official Windows notes are explicit. Linux remains the path they actually test hard; WSL2 is unofficial.

First-time run and verification

No custom YAML for a smoke test. CLI help, then the shipped poster capture:

ns-train --help
ns-download-data nerfstudio --capture-name=poster
ns-train nerfacto --data data/nerfstudio/poster

Watch for iteration timing plus a viewer URL. Websocket default is port 7007; remote boxes need a forward (or --viewer.websocket-port). Metrics moving and a scene that keeps refining in the browser = install OK. Version check: python -c "import nerfstudio; print(nerfstudio.__version__)" when exposed, otherwise trust the git/image tag you pinned.

There’s a strange calm the first time the poster scene snaps into place in the browser – after fighting drivers for an hour, the software suddenly feels simple. That gap between install pain and runtime polish is most of the product.

Think of the install stack like a darkroom: chemicals have to match the film stock or the print never appears. Runtime Nerfstudio is the print. Mixing CUDA 12 host toolkits with a cu118 torch wheel is the classic fogged negative.

Common install errors and fixes

These are the messages that show up in the official FAQ and install threads – not generic “update your drivers.”

• ImportError: DLL load failed while importing _89_C (or similar _XX_C) – tiny-cuda-nn never built your GPU arch. Reinstall with the arch from NVIDIA’s list, e.g. TCNN_CUDA_ARCHITECTURES=89 pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch (89 for 40-series / Ada). On Windows: set TCNN_CUDA_ARCHITECTURES=89 first, in a shell that already ran vcvars.
• The detected CUDA version mismatches the version that was used to compile PyTorch – put the documented torch+cu118 wheel back, then rebuild tinycudann. Do not “fix” this by only upgrading the host toolkit.
• Docker dies under load with no clean Python traceback – raise --shm-size (12gb is the documented starting point) or use --ipc=host.
• Windows build tools “missing” after a fresh terminal – vcvars is session-scoped; activate again before the first splatfacto / tiny-cuda-nn build or after updates.

Mixed CUDA 12 toolkits on the host while torch expects 11.8 still eat multi-hour tinycudann builds. Matching the wheel beats chasing the newest toolkit.

Upgrade and uninstall

Pip env: activate conda, then pip install -U nerfstudio. After a bad torch pull, hard reset: uninstall torch, torchvision, functorch, tinycudann, nerfstudio → reinstall cu118 torch → tinycudann → nerfstudio. Editable tree: git fetch --tags && git checkout tags/v1.1.5 && pip install -e ..

Docker: pull a newer tag, recreate the container. Prune old images only after volumes you care about are safe.

Full conda teardown:conda deactivate && conda remove -n nerfstudio --all. Delete data/ and outputs/ yourself – training artifacts are not wiped by the package.

Per the v1.1.5 notes: gsplat floor ≥1.3.0, splatfacto fixes, viser 0.2.7, Docker build tweaks, Windows pymeshlab pin. No data-format migration called out for standard nerfacto runs. Rebuild custom CUDA extensions after any torch change.

FAQ

Does Nerfstudio run without tiny-cuda-nn?

Don’t plan on it. The documented install builds those bindings for a reason – methods that expect them get slow or break. Install tinycudann.

Docker or conda for a single workstation?

Docker if you want one known-good CUDA 11.8 userspace and you already pass GPUs into containers. Conda if you hack custom methods, need an IDE debugger on a local process, or your cluster blocks Docker. Common hybrid: train in Docker, open exports on the host.

Why pin CUDA 11.8 when my driver supports 12.x?

Drivers stay backward compatible. Extensions do not. The failure mode is compiling tinycudann against a different toolkit than the PyTorch wheel. Documented pair (as of the install guide): torch 2.1.2+cu118 plus the matching conda cuda-toolkit 11.8 label. Cross that pair and every weird link error is on you. CUDA 12 wheels mean you’re off the tested matrix.

Next: pull the image (or finish the conda stack), run the poster train, and only then point ns-process-data at your own video. When the viewer holds a stable mesh of light on footage you shot, the stack has earned the afternoon it cost.