Contributing

Thanks for considering contributing to NVIDIA Isaac GR00T! This guide explains the various ways you can contribute to this project and how to get started.

Bug reports and feature requests

Reporting bugs

Before creating a bug report:

Search existing issues: Do a quick search to see if your issue has already been reported
Comment on existing issues: If your issue exists, add any additional information as a comment

If you’ve confirmed it’s a new issue:

Open a new GitHub issue
Include a clear title and description
Provide:
- Steps to reproduce the error
- Expected behavior vs actual behavior
- Code samples or test cases demonstrating the issue
- Error messages and stack traces
- Environment details (CUDA version, GPU model, OS, etc.)

The more information you provide, the easier it is for maintainers to reproduce and fix the issue.

Suggesting features

Before creating a feature request:

Clarify your idea: Make sure you have a clear vision of the enhancement
Check documentation: Verify the feature doesn’t already exist
Search existing issues: Do a quick search to avoid duplicates

When creating your feature request:

Provide a clear title and description
Explain the use case: Why would this enhancement be useful?
Show examples: Highlight similar features in other libraries if applicable
Include code examples: Demonstrate how the feature would be used

Making a pull request

Follow these guidelines when contributing code to help us review your pull request quickly.

Initial setup (one-time)

Fork the repository

Fork the Isaac GR00T repository on GitHub.

Clone your fork

Clone your fork locally:

git clone https://github.com/USERNAME/Isaac-GR00T.git
# or
git clone git@github.com:USERNAME/Isaac-GR00T.git

Add upstream remote

Add the main repository as an upstream remote:

git remote add upstream https://github.com/NVIDIA/Isaac-GR00T.git

Verify your remotes:

git remote -v

You should see:

origin    https://github.com/USERNAME/Isaac-GR00T.git (fetch)
origin    https://github.com/USERNAME/Isaac-GR00T.git (push)
upstream  https://github.com/NVIDIA/Isaac-GR00T.git (fetch)
upstream  https://github.com/NVIDIA/Isaac-GR00T.git (push)

Install in editable mode

Create a development environment and install GR00T in editable mode:

uv pip install -e .[dev]

The -e flag creates a symbolic link from your virtual environment to your local source code, so changes are immediately reflected.

Keeping your fork up-to-date

Once you’ve added an upstream remote, keeping your fork synchronized is easy:

git checkout main  # if not already on main
git pull --rebase upstream main
git push

Creating a branch for your changes

Committing directly to the main branch of your fork is not recommended. Working on a separate branch for each contribution keeps your fork cleaner.

Create a new branch:

# Replace BRANCH with a descriptive name
git checkout -b BRANCH
git push -u origin BRANCH

Testing your changes

Before opening a pull request, run the following checks locally to speed up the review process.

Code formatting and linting

GR00T uses ruff for code formatting and linting.

Many IDEs support ruff as a plugin, allowing automatic formatting on save. For example, black.vim provides this functionality in Vim.

Run ruff from the command line:

# Format code
ruff format .

# Fix linting issues automatically
ruff check --fix .

Running tests

We strive to maintain high test coverage. Most contributions should include additions to the unit tests. Run tests with pytest:

# Run all tests
pytest -v

# Run specific test module
pytest -v tests/gr00t/data/test_embodiment.py

# Run tests for a specific function you modified
pytest -v tests/gr00t/policy/test_policy.py::test_get_action

Example: If you’ve fixed a bug in gr00t/policy/policy.py, run:

pytest -v tests/gr00t/policy/test_policy.py

Opening a pull request

After all checks have passed:

Open a new GitHub pull request
Provide a clear description of:
- The problem being solved
- Your solution approach
- Links to related issues
Reference any relevant issues (e.g., “Fixes #123”)

We look forward to reviewing your PR! Please be patient as maintainers review contributions.

Developer Certificate of Origin

By making a contribution to this project, you certify that:

Developer's Certificate of Origin 1.1

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Code style guidelines

Python code formatting

Use ruff format for consistent formatting
Use ruff check --fix for linting
Follow PEP 8 guidelines
Maximum line length: 100 characters (enforced by ruff)

Documentation

Write clear docstrings for all public functions and classes
Use Google-style docstring format
Update relevant documentation when changing functionality

Commit messages

Use clear, descriptive commit messages
Start with a verb in present tense (e.g., “Add”, “Fix”, “Update”)
Reference issue numbers when applicable (e.g., “Fix #123: …”)

Example:

Add support for new embodiment tag

- Implement NEW_EMBODIMENT configuration
- Add tests for new modality config
- Update documentation

Fixes #456

Testing guidelines

Writing tests

Place tests in tests/ directory matching the source structure
Name test files with test_ prefix (e.g., test_policy.py)
Use descriptive test function names (e.g., test_get_action_with_valid_observation)
Include both positive and negative test cases
Test edge cases and error conditions

Test coverage

Aim for high test coverage of new code
Run tests locally before submitting PR
CI will run full test suite on all supported platforms

Continuous Integration

All pull requests run through our CI pipeline on GitHub Actions, which checks:

Code formatting: ruff format --check
Linting: ruff check
Unit tests: pytest
Type checking: mypy (if configured)

Your PR must pass all CI checks before it can be merged.

Getting help

If you need help with your contribution:

Ask questions in your pull request
Comment on related issues
Check existing documentation and examples
Review similar merged pull requests for guidance

License

By contributing to Isaac GR00T, you agree that your contributions will be licensed under the Apache License 2.0.

SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Thank you

Thank you for contributing to NVIDIA Isaac GR00T! Your contributions help advance the state of robotics research and make foundation models more accessible to the community.

Overview

Getting Started

Core Concepts

Guides

Benchmarks & Examples

Deployment

Resources

Bug reports and feature requests

Reporting bugs

Suggesting features

Making a pull request

Initial setup (one-time)

Keeping your fork up-to-date

Creating a branch for your changes

Testing your changes

Code formatting and linting

Running tests

Opening a pull request

Developer Certificate of Origin

Code style guidelines

Python code formatting

Documentation

Commit messages

Testing guidelines

Writing tests

Test coverage

Continuous Integration

Getting help

License

Thank you

Build docs developers (and LLMs) love

Overview

Getting Started

Core Concepts

Guides

Benchmarks & Examples

Deployment

Resources

Documentation Index

​Bug reports and feature requests

​Reporting bugs

​Suggesting features

​Making a pull request

​Initial setup (one-time)

​Keeping your fork up-to-date

​Creating a branch for your changes

​Testing your changes

​Code formatting and linting

​Running tests

​Opening a pull request

​Developer Certificate of Origin

​Code style guidelines

​Python code formatting

​Documentation

​Commit messages

​Testing guidelines

​Writing tests

​Test coverage

​Continuous Integration

​Getting help

​License

​Thank you

Build docs developers (and LLMs) love

Bug reports and feature requests

Reporting bugs

Suggesting features

Making a pull request

Initial setup (one-time)

Keeping your fork up-to-date

Creating a branch for your changes

Testing your changes

Code formatting and linting

Running tests

Opening a pull request

Developer Certificate of Origin

Code style guidelines

Python code formatting

Documentation

Commit messages

Testing guidelines

Writing tests

Test coverage

Continuous Integration

Getting help

License

Thank you