Skip to content

Commit b5c7a04

Browse files
authored
docs: add Windows WSL2 setup section (#2065)
* Takes work contributed by @hemachandra666 in PR #1951 and re-targets the PR towards the `release/1.8` branch. * Includes some reformatting ## By Submitting this PR I confirm: - I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/NeMo-Agent-Toolkit/blob/develop/docs/source/resources/contributing/index.md). - We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license. - Any contribution which contains commits that are not Signed-Off will not be accepted. - When the PR is ready for review, new or existing tests cover these changes. - When the PR is ready for review, the documentation is up to date with these changes. ## Summary by CodeRabbit * **Documentation** * Updated installation guide to include Windows (WSL2) as a supported platform. * Added dedicated Windows (WSL2) installation section with step-by-step setup instructions, including WSL2 and Ubuntu prerequisites. * Added Windows-specific recommendation to use WSL2 during installation process. Authors: - David Gardner (https://github.com/dagardner-nv) - Kunchala Hema Sai Venkat Chandra Kumar (https://github.com/hemachandra666) Approvers: - https://github.com/mnajafian-nv URL: #2065
1 parent 5655a24 commit b5c7a04

1 file changed

Lines changed: 61 additions & 0 deletions

File tree

docs/source/get-started/installation.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,8 @@ To install these first-party plugin libraries, you can use the full distribution
7878
| Linux | aarch64 | 3.11, 3.12, 3.13 | ✅ Tested, Validated in CI |
7979
| macOS | x86_64 | 3.11, 3.12, 3.13 | ❓ Untested, Should Work |
8080
| macOS | aarch64 | 3.11, 3.12, 3.13 | ✅ Tested |
81+
| [Windows (WSL2)](#windows-wsl2) | x86_64 | 3.11, 3.12, 3.13 | ✅ Tested |
82+
| [Windows (WSL2)](#windows-wsl2) | aarch64 | 3.11, 3.12, 3.13 | ❓ Untested, Should Work |
8183
| Windows | x86_64 | 3.11, 3.12, 3.13 | ❓ Untested, Should Work |
8284
| Windows | aarch64 | 3.11, 3.12, 3.13 | ❌ Unsupported |
8385

@@ -120,6 +122,8 @@ The full list of optional dependencies can be found [here](#packages).
120122
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).
121123
:::
122124

125+
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.
126+
123127
Installing from source is required to run any examples provided in the repository or to contribute to the project.
124128

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

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

191+
## Windows (WSL2)
192+
193+
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.
194+
195+
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.
196+
197+
### Install WSL2 and Ubuntu
198+
199+
From an Administrator PowerShell session, install WSL2 with an Ubuntu distribution, then restart the machine when prompted:
200+
201+
```bash
202+
wsl --install -d Ubuntu-24.04
203+
```
204+
205+
:::{note}
206+
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.
207+
:::
208+
209+
### Set up the Linux user
210+
211+
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.
212+
213+
:::{note}
214+
To set or change the password later, run the following from an Administrator PowerShell session, replacing `<username>` with your Linux username:
215+
216+
```bash
217+
wsl -u root
218+
passwd <username>
219+
exit
220+
```
221+
:::
222+
223+
### Install build prerequisites
224+
225+
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:
226+
227+
```bash
228+
sudo apt update && sudo apt install -y curl git build-essential git-lfs
229+
```
230+
231+
### Install uv
232+
233+
Install [`uv`](https://docs.astral.sh/uv/) into your user directory:
234+
235+
```bash
236+
curl -LsSf https://astral.sh/uv/install.sh | sh
237+
```
238+
239+
:::{note}
240+
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`.
241+
:::
242+
243+
### Continue with Install From Source
244+
245+
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.
246+
247+
187248
## Next Steps
188249

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

0 commit comments

Comments
 (0)