NuScenes Devkit

Common errors

• FileNotFoundError: [Errno 2] No such file or directory: '{dataroot}/meta.json'

  cause 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'

  cause 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

  cause 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'

  cause 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.

Warnings

• breaking Version 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.
• gotcha The `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.
• gotcha Incorrect `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`).
• gotcha Deep 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.

Install

• pip install nuscenes-devkit Install core devkit
• pip install 'nuscenes-devkit[dl]' Install with Deep Learning dependencies (e.g., PyTorch)

Imports

• NuScenes
  wrong:

  from nuscenes_devkit.nuscenes import NuScenes

  correct:

  from nuscenes.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

Quickstart

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}")