Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions docs/source/get-started/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,8 @@ To install these first-party plugin libraries, you can use the full distribution
| Linux | aarch64 | 3.11, 3.12, 3.13 | ✅ Tested, Validated in CI |
| macOS | x86_64 | 3.11, 3.12, 3.13 | ❓ Untested, Should Work |
| macOS | aarch64 | 3.11, 3.12, 3.13 | ✅ Tested |
| [Windows (WSL2)](#windows-wsl2) | x86_64 | 3.11, 3.12, 3.13 | ✅ Tested |
| [Windows (WSL2)](#windows-wsl2) | aarch64 | 3.11, 3.12, 3.13 | ❓ Untested, Should Work |
| Windows | x86_64 | 3.11, 3.12, 3.13 | ❓ Untested, Should Work |
| Windows | aarch64 | 3.11, 3.12, 3.13 | ❌ Unsupported |

Expand Down Expand Up @@ -120,6 +122,8 @@ The full list of optional dependencies can be found [here](#packages).
Using Conda environments is not recommended and may cause component resolution issues. Only create vanilla Python virtual environments through `python -m venv` or `uv venv` with no other active environments. For more information, see the [Troubleshooting Guide](../resources/troubleshooting.md#workflow-issues).
:::

For Windows users, it is recommended to run NeMo Agent Toolkit inside WSL2. Follow the [Windows (WSL2)](#windows-wsl2) section below for Windows-specific installation instructions.

Installing from source is required to run any examples provided in the repository or to contribute to the project.

1. Clone the NeMo Agent Toolkit repository to your local machine.
Expand Down Expand Up @@ -184,6 +188,63 @@ Installing from source is required to run any examples provided in the repositor

If the installation succeeded, the `nat` command will log the help message and its current version.

## Windows (WSL2)

NeMo Agent Toolkit is developed and tested on Linux and macOS. On Windows, the recommended path is to run the toolkit inside the Windows Subsystem for Linux 2 (WSL2). The steps in this section were verified on Windows 11 with Ubuntu 24.04 LTS.

Complete the Windows-specific steps below, then continue with the standard [Install From Source](#install-from-source) steps, running every command inside the WSL2 Ubuntu shell.

### Install WSL2 and Ubuntu

From an Administrator PowerShell session, install WSL2 with an Ubuntu distribution, then restart the machine when prompted:

```bash
wsl --install -d Ubuntu-24.04
```

:::{note}
To check whether WSL2 is already installed, run `wsl --status`. If the output reports a default distribution and `Default Version: 2`, WSL2 is ready and you can skip to the next step.
:::

### Set up the Linux user

The first time Ubuntu launches, it prompts you to create a Linux username and password. This password is separate from the Windows password and is used for `sudo` commands inside Ubuntu.

:::{note}
To set or change the password later, run the following from an Administrator PowerShell session, replacing `<username>` with your Linux username:

```bash
wsl -u root
passwd <username>
exit
```
:::

### Install build prerequisites

Open Ubuntu (from the Start menu, or by running `wsl` in PowerShell) and install the build tools. Git Large File Storage (LFS) is required by the repository and is not included in the default Ubuntu image:

```bash
sudo apt update && sudo apt install -y curl git build-essential git-lfs
```

### Install uv

Install [`uv`](https://docs.astral.sh/uv/) into your user directory:

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

:::{note}
After installing, run `source $HOME/.local/bin/env` in the current shell, or close and reopen Ubuntu, so that the `uv` command is on your `PATH`.
:::

### Continue with Install From Source

Follow the [Install From Source](#install-from-source) steps below. Run every command inside the WSL2 Ubuntu shell, not in PowerShell or `cmd`. After activating the virtual environment, the shell prompt begins with `(.venv)`; activate the environment in every new Ubuntu session before running `nat` or `uv` commands.

Comment thread
dagardner-nv marked this conversation as resolved.

## Next Steps

* Follow the [Quick Start Guide](./quick-start.md) to get started running workflows with NeMo Agent Toolkit.