docs/docs/en/ai/windows-wsl.md
For local NocoBase development on Windows, we recommend preparing WSL 2 first. This lets Node.js, Yarn, NocoBase CLI, Docker commands, and AI Agents run in the same Linux shell, with paths, permissions, and native dependency builds closer to common Linux deployment environments.
If you are not sure whether you need WSL, see Local Development Setup first.
Before installing WSL, check your Windows version and virtualization status.
Press Win + R, enter winver, and confirm that your system meets one of the following requirements:
If your version is older, upgrade Windows before continuing.
Open Task Manager, go to Performance / CPU, and confirm that Virtualization is shown as Enabled.
If virtualization is not enabled, enable it in BIOS / UEFI. The option name varies by vendor, such as Intel VT-x, Intel Virtualization Technology, AMD-V, or SVM Mode.
Open PowerShell as administrator:
PowerShellRun:
wsl --install
Restart your computer after installation.
By default, this command installs Ubuntu. When Ubuntu starts for the first time, it asks you to create a Linux username and password. This username and password are only used inside WSL and do not need to match your Windows account.
To install a specific distribution, list the available distributions first:
wsl --list --online
Then install a distribution, such as Ubuntu:
wsl --install -d Ubuntu
Run the following command in PowerShell:
wsl --list --verbose
The output should look like this:
NAME STATE VERSION
* Ubuntu Running 2
Confirm that VERSION is 2. If a distribution is still using WSL 1, convert it to WSL 2:
wsl --set-version Ubuntu 2
We also recommend setting WSL 2 as the default version for newly installed distributions:
wsl --set-default-version 2
You can also update WSL once:
wsl --update
If you plan to install or run NocoBase with Docker, install Docker Desktop for Windows.
Download the installer from the Docker documentation:
During installation, pay attention to these options:
Per-user for personal local developmentUse WSL 2 instead of Hyper-VAfter Docker Desktop starts, first confirm that the WSL 2 backend is enabled:
Then enable distribution integration:
UbuntuIf WSL Integration does not appear under Resources, Docker Desktop is usually in Windows containers mode. Click the Docker icon in the Windows system tray, switch to Linux containers, and check again.
First verify from PowerShell:
wsl --list --verbose
docker version
docker compose version
docker run hello-world
Then enter WSL:
wsl
Run the following commands inside WSL:
docker version
docker compose version
docker run hello-world
If the hello-world container is pulled and runs successfully, Docker Desktop and WSL 2 integration are working.
WSL itself is not a Node.js runtime environment. Ubuntu installed through wsl --install usually does not include Node.js or npm, so install them inside the WSL distribution.
Enter WSL from PowerShell:
wsl
All commands below are run in the WSL terminal.
First check whether Node.js is already installed:
node -v
npm -v
If you see command not found, install Node.js with one of the following methods.
If this WSL environment only needs one shared Node.js version, NodeSource is recommended.
sudo apt update
sudo apt install -y curl
curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install -y nodejs
Verify the installation:
node -v
npm -v
npx -v
If you need to switch Node.js versions across projects, or if a project uses .nvmrc to pin the version, use nvm.
sudo apt update
sudo apt install -y curl ca-certificates
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
Verify the installation:
node -v
npm -v
npx -v
If the project root needs to pin Node.js 22, create .nvmrc:
echo "22" > .nvmrc
nvm install
nvm use
Later, run this command after entering the project directory:
nvm use
This switches to the version specified by the project.
:::warning Note
Choose either NodeSource or nvm. We do not recommend mixing both Node.js management methods in the same WSL user environment.
:::
NocoBase local development requires Yarn 1.x. After Node.js is installed, you can enable Yarn through Corepack:
corepack enable
corepack prepare [email protected] --activate
yarn -v
If Corepack is not available in your environment, install Yarn with npm:
npm install -g [email protected]
yarn -v
Codex CLI can also be used in the native Windows command line. In this guide, it is installed inside WSL so Codex and the NocoBase local toolchain stay in the same Linux environment. When Codex runs commands such as nb, yarn, or docker, it uses the same file paths, shell syntax, and runtime environment.
Confirm that you are currently inside WSL:
echo $WSL_DISTRO_NAME
If it outputs a distribution name such as Ubuntu, you are inside WSL.
Run the Codex CLI installer inside WSL:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
For non-interactive installation, use:
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh
After installation, run:
codex
The first run prompts you to sign in. Follow the prompts and authenticate with a ChatGPT account or OpenAI API key.
Verify that the Codex command is available:
codex --version
We recommend starting Codex from a project directory inside WSL:
mkdir -p ~/projects
cd ~/projects/my-app
codex
:::tip Note
Because Codex is installed inside WSL, run codex from the WSL terminal afterward. If you run codex from Windows PowerShell, it uses the native Windows command-line environment, which is not the same environment prepared in this guide.
:::
We recommend putting project files inside the WSL filesystem, for example:
~/projects/my-app
Avoid using the Windows mounted path as the default project location, for example:
/mnt/c/Users/<your-name>/projects/my-app
This usually gives better filesystem performance and reduces symlink and permission issues. The difference is especially visible for projects with many dependency files, such as Node.js, Python, Java, or Go projects.
To access WSL files from Windows Explorer, open:
\\wsl$\Ubuntu\home\<your-name>
First confirm that the distribution uses WSL 2:
wsl --list --verbose
If it is WSL 1, convert it to WSL 2:
wsl --set-version Ubuntu 2
Then return to Docker Desktop, go to Settings / Resources / WSL Integration, enable integration for the corresponding distribution, and apply the change.
Usually, Docker Desktop is currently in Windows containers mode.
You can handle it like this:
Try this first:
wsl --shutdown
wsl --update
Then restart Docker Desktop.
Docker recommends uninstalling Docker Engine or Docker CLI that was installed directly inside the WSL Linux distribution before installing Docker Desktop. Otherwise, it may conflict with Docker Desktop WSL integration.
Usually, uninstall docker-ce, docker-ce-cli, containerd.io, and related packages inside the WSL distribution, and then use the Docker CLI integration provided by Docker Desktop.
First confirm that you are running the command inside WSL, not PowerShell:
echo $WSL_DISTRO_NAME
Then check whether Codex is in PATH:
which codex
If it cannot be found, reopen the WSL terminal or run the installer again:
curl -fsSL https://chatgpt.com/codex/install.sh | sh