Install & Compatibility
Where this runs
tested against v1.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 17.79s
py 3.11
✕ build_error
✓ 15.55s
py 3.12
✕ build_error
✓ 15.46s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 20.14s
525MB installed
● package 525MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NuScenes
✓ from nuscenes.nuscenes import NuScenes
✗ from nuscenes_devkit.nuscenes import NuScenes
The top-level package for the devkit is `nuscenes`, not `nuscenes_devkit`.
NuScenesExplorer
✓ from nuscenes.nuscenes_explorer import NuScenesExplorer
NuScenesMap
✓ from nuscenes.nuscenes_map import NuScenesMap
This quickstart demonstrates how to initialize the `NuScenes` object, which is the primary entry point for interacting with the dataset. It highlights the critical `dataroot` and `version` parameters, which must correspond to your locally downloaded and extracted NuScenes data. The code also includes basic error handling for common setup issues.
import os
from nuscenes.nuscenes import NuScenes
# IMPORTANT: Before running, you must download a NuScenes dataset split
# (e.g., v1.0-mini) from www.nuscenes.org and extract it.
# The 'dataroot' should point to the directory containing 'sets/nuscenes'.
# Example directory structure: /your/chosen/root/sets/nuscenes/v1.0-mini
# Replace with the actual path to your NuScenes data root directory
dataroot = os.environ.get('NUSCENES_DATAROOT', '/tmp/nuscenes_data_root')
# Replace with the dataset version you downloaded (e.g., 'v1.0-trainval', 'v1.0-mini')
version = os.environ.get('NUSCENES_VERSION', 'v1.0-mini')
try:
# Initialize the NuScenes object
nusc = NuScenes(version=version, dataroot=dataroot, verbose=True)
print(f"Successfully loaded NuScenes dataset version '{nusc.version}' from '{nusc.dataroot}'")
# Print some basic statistics
print(f"Number of scenes: {len(nusc.scene)}")
print(f"Number of samples: {len(nusc.sample)}")
# Example: Access the first scene
first_scene = nusc.scene[0]
print(f"\nFirst scene name: {first_scene['name']}")
print(f"First scene description: {first_scene['description']}")
except ValueError as e:
print(f"Error initializing NuScenes: {e}")
print("Please ensure 'dataroot' and 'version' are correctly set and the dataset is downloaded.")
except FileNotFoundError as e:
print(f"Error loading NuScenes data: {e}")
print("Ensure the dataset is extracted and 'dataroot' points to the correct location.")
print("Expected structure inside dataroot: sets/nuscenes/<version>/")
except Exception as e:
print(f"An unexpected error occurred: {e}")
nuscenes --version
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: '{dataroot}/meta.json'
The `dataroot` path provided to `NuScenes()` is incorrect, or the dataset has not been fully extracted into the expected folder structure.
fixVerify that `dataroot` points to the parent directory of `sets/nuscenes/` and that the specified dataset `version` folder exists within `sets/nuscenes` (e.g., `dataroot/sets/nuscenes/v1.0-mini/`). Download and extract the dataset if not already done.
ModuleNotFoundError: No module named 'nuscenes'
The `nuscenes-devkit` package is either not installed, or you are attempting to import it incorrectly (e.g., `import nuscenes_devkit`).
fixEnsure the package is installed using `pip install nuscenes-devkit`. The correct import statement is `from nuscenes.nuscenes import NuScenes` (or other submodules within `nuscenes`).
ValueError: Cannot find version v1.0-invalid_version in dataroot /path/to/data
The `version` string provided to `NuScenes()` does not match any of the extracted dataset versions available in the specified `dataroot`.
fixCheck the exact name of the dataset folder (e.g., `v1.0-mini`, `v1.0-trainval`) within `dataroot/sets/nuscenes/` and update the `version` parameter in your code to match.
ModuleNotFoundError: No module named 'torch'
You are trying to use a feature of the devkit that relies on PyTorch (e.g., certain evaluation metrics, `mmdet` integration) without having the `torch` dependency installed.
fixInstall the NuScenes Devkit with its deep learning dependencies: `pip install 'nuscenes-devkit[dl]'`. If you need specific PyTorch versions or CUDA support, install `torch` separately according to its official instructions before installing the devkit's `[dl]` extra.
Upgrade
Version history
1.2.0latest on PyPI · released Aug 28, 2025
Audit
Dependencies
numpyrequiredFundamental array operations for data processing.
PillowrequiredImage processing for visual data.
matplotlibrequiredPlotting and visualization of data and results.
pyquaternionrequiredHandling 3D rotations and orientations.
opencv-pythonrequiredComputer vision tasks, particularly for image and video processing.
torchoptionalRequired for deep learning functionalities and specific evaluation metrics (installed via `[dl]` extra).
torchvisionoptionalRequired for deep learning functionalities, complements `torch` (installed via `[dl]` extra).