{"id":8360,"library":"nuscenes-devkit","title":"NuScenes Devkit","description":"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.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/nutonomy/nuscenes-devkit","tags":["computer vision","dataset","autonomous driving","3D perception","robotics"],"install":[{"cmd":"pip install nuscenes-devkit","lang":"bash","label":"Install core devkit"},{"cmd":"pip install 'nuscenes-devkit[dl]'","lang":"bash","label":"Install with Deep Learning dependencies (e.g., PyTorch)"}],"dependencies":[{"reason":"Fundamental array operations for data processing.","package":"numpy","optional":false},{"reason":"Image processing for visual data.","package":"Pillow","optional":false},{"reason":"Plotting and visualization of data and results.","package":"matplotlib","optional":false},{"reason":"Handling 3D rotations and orientations.","package":"pyquaternion","optional":false},{"reason":"Computer vision tasks, particularly for image and video processing.","package":"opencv-python","optional":false},{"reason":"Required for deep learning functionalities and specific evaluation metrics (installed via `[dl]` extra).","package":"torch","optional":true},{"reason":"Required for deep learning functionalities, complements `torch` (installed via `[dl]` extra).","package":"torchvision","optional":true}],"imports":[{"note":"The top-level package for the devkit is `nuscenes`, not `nuscenes_devkit`.","wrong":"from nuscenes_devkit.nuscenes import NuScenes","symbol":"NuScenes","correct":"from nuscenes.nuscenes import NuScenes"},{"symbol":"NuScenesExplorer","correct":"from nuscenes.nuscenes_explorer import NuScenesExplorer"},{"symbol":"NuScenesMap","correct":"from nuscenes.nuscenes_map import NuScenesMap"}],"quickstart":{"code":"import os\nfrom nuscenes.nuscenes import NuScenes\n\n# IMPORTANT: Before running, you must download a NuScenes dataset split\n# (e.g., v1.0-mini) from www.nuscenes.org and extract it.\n# The 'dataroot' should point to the directory containing 'sets/nuscenes'.\n# Example directory structure: /your/chosen/root/sets/nuscenes/v1.0-mini\n\n# Replace with the actual path to your NuScenes data root directory\ndataroot = os.environ.get('NUSCENES_DATAROOT', '/tmp/nuscenes_data_root')\n# Replace with the dataset version you downloaded (e.g., 'v1.0-trainval', 'v1.0-mini')\nversion = os.environ.get('NUSCENES_VERSION', 'v1.0-mini')\n\ntry:\n    # Initialize the NuScenes object\n    nusc = NuScenes(version=version, dataroot=dataroot, verbose=True)\n    print(f\"Successfully loaded NuScenes dataset version '{nusc.version}' from '{nusc.dataroot}'\")\n\n    # Print some basic statistics\n    print(f\"Number of scenes: {len(nusc.scene)}\")\n    print(f\"Number of samples: {len(nusc.sample)}\")\n\n    # Example: Access the first scene\n    first_scene = nusc.scene[0]\n    print(f\"\\nFirst scene name: {first_scene['name']}\")\n    print(f\"First scene description: {first_scene['description']}\")\n\nexcept ValueError as e:\n    print(f\"Error initializing NuScenes: {e}\")\n    print(\"Please ensure 'dataroot' and 'version' are correctly set and the dataset is downloaded.\")\nexcept FileNotFoundError as e:\n    print(f\"Error loading NuScenes data: {e}\")\n    print(\"Ensure the dataset is extracted and 'dataroot' points to the correct location.\")\n    print(\"Expected structure inside dataroot: sets/nuscenes/<version>/\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `dataroot` path provided to `NuScenes()` is incorrect, or the dataset has not been fully extracted into the expected folder structure.","error":"FileNotFoundError: [Errno 2] No such file or directory: '{dataroot}/meta.json'"},{"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`).","cause":"The `nuscenes-devkit` package is either not installed, or you are attempting to import it incorrectly (e.g., `import nuscenes_devkit`).","error":"ModuleNotFoundError: No module named 'nuscenes'"},{"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.","cause":"The `version` string provided to `NuScenes()` does not match any of the extracted dataset versions available in the specified `dataroot`.","error":"ValueError: Cannot find version v1.0-invalid_version in dataroot /path/to/data"},{"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.","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.","error":"ModuleNotFoundError: No module named 'torch'"}]}