Registry / data / nuscenes-devkit

nuscenes-devkit

JSON →
library1.2.0pypypi✓ verified 85d ago

The NuScenes Devkit is the official Python toolkit for interacting with the NuScenes dataset, a large-scale dataset for autonomous driving. It provides functionalities for loading, processing, visualizing, and evaluating data from the NuScenes and NuImages datasets. The current version is 1.2.0, with a release cadence that includes several minor updates and bug fixes per year, alongside occasional major updates for new dataset releases or features.

pip install nuscenes-devkit
INSTALL
IMPORT
SIG · NUSCENES-DEVKIT
N
nuscenes-devkit
datapythonv1.2.0
Install
17.2s avg
Import
5271ms
Disk
525MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
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
Debug
Known issues
breakingVersion 1.0.0 introduced significant breaking changes, dropping support for teaser data, reorganizing code, and altering map tables/files. Projects built with pre-1.0.0 versions are not directly compatible.
fix
For older projects, refer to the documentation for the specific older version. For new projects, always use the latest devkit and dataset versions. Migration may require significant code refactoring for pre-1.0.0 projects.
affects: <1.0.0
gotchaThe `nuscenes-devkit` Python package does NOT include the actual NuScenes dataset. The dataset is extremely large (e.g., >100 GB for the full dataset) and must be downloaded separately from the official NuScenes website.
fix
Download the desired NuScenes dataset split (e.g., v1.0-mini, v1.0-trainval) from www.nuscenes.org, extract it, and set the `dataroot` parameter correctly when initializing the `NuScenes` object.
affects: All versions
gotchaIncorrect `dataroot` or dataset `version` string (e.g., `v1.0-trainval`) is the most common cause of errors. The `dataroot` must point to the directory containing the `sets/nuscenes` folder, and the version string must exactly match the extracted dataset subfolder (e.g., `v1.0-mini`).
fix
Double-check the path provided to `dataroot` and ensure it's the parent directory of `sets/nuscenes`. Verify that the `version` string matches the name of the folder inside `sets/nuscenes` (e.g., `v1.0-mini`).
affects: All versions
gotchaDeep learning functionalities (e.g., using `mmdet` models or certain evaluation scripts) require optional dependencies like PyTorch and torchvision. These are not installed by default.
fix
Install the devkit with the `[dl]` extra: `pip install 'nuscenes-devkit[dl]'`. Ensure your PyTorch installation is compatible with your Python version and CUDA setup if applicable.
affects: All versions
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.
fix
Verify 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`).
fix
Ensure 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`.
fix
Check 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.
fix
Install 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).
Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources