Installation#

This guide will help you install Newton and set up your Python environment.

System Requirements#

Python 3.10 or higher
Windows or Linux on x86-64 architecture (to be expanded to more platforms and architectures soon)
NVIDIA GPU with compute capability >= 5.0 (Maxwell) and driver 545 or newer (see note below)

A local installation of the CUDA Toolkit is not required for Newton.

Note:

NVIDIA GPU driver 545+ is required for Warp kernel compilation during CUDA graph capture. Some examples using graph capture may fail with older drivers.
Unless otherwise specified, Newton’s system requirements are identical to NVIDIA’s Warp requirements.

1. Clone the repository#

git clone git@github.com:newton-physics/newton.git
cd newton

2. Python Environment Setup#

We recommend using the uv Python package and project manager. It will automatically setup a version-locked Python environment based on the uv.lock file that the Newton team maintains.

Note

During the alpha development phase, we recommend using uv. When Newton is stabilized and regularly publishing to PyPI we will update this guide to make the pip install approach the recommended method.

Extra Dependencies#

Newton’s only mandatory dependency is NVIDIA Warp. We define additional dependency sets in the pyproject.toml file. The sets are:

Set	Purpose
`sim`	Simulation dependencies, including MuJoCo
`importers`	Asset import and mesh processing dependencies
`examples`	Dependencies for running examples, including visualization
`torch-cu12`	PyTorch dependency needed in addition to `examples` dependencies to run examples that inference RL-trained control policies
`dev`	Dependencies for development and testing
`docs`	Dependencies for building the documentation

Method 1: Using uv (Recommended)#

Install uv:

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

See also instructions on updating packages in the uv lockfile in the Development.

Running Newton with uv#

Run an example with minimal dependencies:

uv run -m newton.examples basic_pendulum --viewer null

Run an example with additional dependencies:

uv run --extra examples -m newton.examples robot_humanoid --num-envs 16

Run an example that inferences an RL policy:

uv run --extra examples --extra torch-cu12 -m newton.examples robot_anymal_c_walk

See a list of all available examples with:

uv run -m newton.examples

Method 2: Using a Virtual Environment Setup by uv#

uv can also be used to setup a virtual environment based on the uv.lock file. You can setup a virtual environment with all examples dependencies by running:

uv venv
uv sync --extra examples

Then you can activate the virtual environment and run an example using the virtual environment’s Python:

macOS / Linux

source .venv/bin/activate
python newton/examples/robot/example_robot_humanoid.py

Windows (console)

.venv\Scripts\activate.bat
python newton/examples/robot/example_robot_humanoid.py

Windows (PowerShell)

.venv\Scripts\Activate.ps1
python newton/examples/robot/example_robot_humanoid.py

Method 3: Manual Setup Using Pip in a Virtual Environment#

These instructions are meant for users who wish to set up a development environment using venv or Conda (e.g. from Miniforge).

macOS / Linux

python -m venv .venv
source .venv/bin/activate

Windows (console)

python -m venv .venv
.venv\Scripts\activate.bat

Windows (PowerShell)

python -m venv .venv
.venv\Scripts\Activate.ps1

Installing dependencies including optional development dependencies:

python -m pip install mujoco --pre -f https://py.mujoco.org/
python -m pip install warp-lang --pre -U -f https://pypi.nvidia.com/warp-lang/
python -m pip install git+https://github.com/google-deepmind/mujoco_warp.git@main
python -m pip install -e .[dev]

Test the installation by running an example:

python newton/examples/robot/example_robot_humanoid.py

Next Steps#

Explore more examples in the newton/examples/ directory and checkout the Visualization guide to learn how to interact with the examples simulation.
Check out the Development guide to learn how to contribute to Newton.