Claude Code is Anthropic’s agentic coding tool. It can inspect and edit code, run terminal commands, and work with files in your local development environment.
Claude Code can start, but it cannot complete tasks that require terminal commands. You may see a message that a command was refused, unavailable, or could not run in the required sandbox.
WSL2 is not supported or managed by Wharton Computing as a workaround for this issue. However, it may provide a technical path forward because it can support the sandbox that Claude Code requires. If you have local administrator access and choose to set it up, you can try the steps below at your own risk.
Before you begin: WSL2 installation can require local administrator access, Windows virtualization features, a Linux distribution, and a restart. Wharton Computing cannot guarantee this configuration or provide device-specific WSL2 troubleshooting. Use only approved, non-sensitive test code while you set it up. Do not disable Claude Code security settings to make it work.
Prerequisites
- You must have local administrator rights on the computer.
- Claude Desktop must already be installed. This WSL2 path uses the Code tab in Claude Desktop.
- Use an approved, non-sensitive project. Do not use secrets, passwords, API keys, private keys, PII, FERPA data, or production access while testing this unsupported configuration.
Use Terminal for the Windows and WSL commands below. When a step says Terminal (Admin), right-click the Windows Start button and select Terminal (Admin). When a step says Terminal, select Terminal, not the administrator option. Once you open Ubuntu, use its Linux terminal for all Linux and Claude Code commands. Claude Code must be installed and launched inside the WSL terminal, not from the Windows terminal.
1. Set up WSL2 (skip if it is already installed)
Right-click the Windows Start button, select Terminal (Admin), and run:
wsl --install
Windows enables the required features and installs Ubuntu. Restart the computer when Windows prompts you to do so.
After restarting, Ubuntu might not open or finish installing automatically. If that happens, right-click the Windows Start button again, select Terminal (Admin), and run wsl --install again. Leave Terminal open while Ubuntu finishes its first launch.
When prompted to create a default UNIX user account, use <pennkey>-wsl as the username. Create and save a separate Linux password. Depending on the Ubuntu version, password characters may not display or may display as asterisks; both are normal.
If you see “A specified logon session does not exist. It may already have been terminated.”
This can be an administrator-session problem, including when separate administrator credentials were entered through a UAC prompt. If this is a managed or work computer, ask your IT administrator to resolve the Windows administrator-session issue. Do not try to bypass it.
2. Verify that Ubuntu is running WSL2
If you are at an Ubuntu prompt after Step 1, run exit to return to Windows. Alternatively, right-click the Windows Start button and select a separate, standard Terminal window. Then run:
wsl -l -v
Look at the VERSION column next to Ubuntu. If 1 is listed, convert that distribution using the name shown in the NAME column:
wsl --set-version <NAME> 2
Conversion can take time. Back up important files before converting an existing distribution.
3. Open the WSL terminal
If Step 1 left you at an Ubuntu prompt, you are already in WSL. Continue to Step 4. If you ran exit or opened a new Terminal window for Step 2, right-click the Windows Start button, select standard Terminal, and run:
wsl
Your prompt should change to something like username@computername:~$. You are now in Ubuntu. Keep this window open for the remaining Linux and Claude Code commands.
4. Install Claude Code inside Ubuntu
In the Ubuntu terminal, run the recommended installer:
curl -fsSL https://claude.ai/install.sh | bash
If the installer finishes with setup notes that state that the native installation location is not in your PATH, add it and apply the change with this single command:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
5. Install the sandbox dependencies
Claude Code’s WSL2 sandbox requires two Linux packages:
sudo apt update
sudo apt install -y bubblewrap socat
Enter the Linux password you created in Step 1, not your Windows password. On some Ubuntu versions, nothing appears while you type; on others, asterisks appear. Both are normal.
Ubuntu 24.04 or later only: allow bubblewrap user namespaces
On Ubuntu 24.04 and later, AppArmor can prevent bubblewrap from creating the user namespaces it needs. In the Ubuntu terminal, check the setting:
sysctl kernel.apparmor_restrict_unprivileged_userns
If the result is 0, or you see sysctl: cannot stat /proc/sys/kernel/apparmor_restrict_unprivileged_userns: No such file or directory, skip this section. If the result is 1, Anthropic documents the following profile and reload command:
sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>
profile bwrap /usr/bin/bwrap flags=(unconfined) {
userns,
include if exists <local/bwrap>
}
EOF
sudo systemctl reload apparmor
This profile applies to bwrap, not directly to the commands it runs in the sandbox. If the reload command fails, do not substitute a different security configuration; stop using this path or consult the Anthropic sandbox documentation.
6. Connect Claude Desktop to the WSL2 project
First, create the project folder Claude Desktop will use. In the Ubuntu terminal, run:
mkdir -p $HOME/projects
This creates projects inside your own Linux home folder. Then:
- Open the Claude Desktop app and authenticate to your enterprise account if prompted.
- Select the Code tab.
- Above the chat box at the bottom of the window, click Local → WSL → Ubuntu.
- Click Select folder…, then select home → <pennkey>-wsl → projects. If you used a different Linux username, select that home folder instead.
Choose the project folder, not a system or Windows mount.
Do not select /home by itself, /mnt/wsl, or /mnt/c/. These locations can be unwritable or cause errors. Keep project files under your own Linux home directory.
7. Use Claude Code and check the sandbox
In Claude Desktop, type a small request in plain English. Start with a read-only request in an approved test project, such as: “List the top-level files in this project. Do not change anything.”
If you prefer the CLI, change to the project directory in Ubuntu and run:
cd $HOME/projects
claude
Inside a Claude Code session, enter /sandbox to check the selected mode, dependencies, overrides, and configuration. For a first test, choose regular permissions so Claude Code continues to ask before commands run. Do not enable an unsandboxed fallback or change a required security setting to make a command work.
Expected limitation: A sandboxed WSL2 command may not be able to launch Windows programs such as cmd.exe, powershell.exe, or tools stored under /mnt/c/. Use Linux tools inside WSL2. Do not weaken the sandbox simply to launch a Windows executable.
Common WSL2 setup problems
| What you see |
What to do |
|---|
Sandboxing requires WSL2 |
In standard Terminal, run wsl --list --verbose. If Ubuntu has 1 in the VERSION column, use wsl --set-version <NAME> 2, replacing <NAME> with its NAME-column value. |
cannot execute binary file: Exec format error |
This is a WSL1 problem. Convert the distribution to WSL2 rather than using the WSL1 workaround. |
claude: command not found |
Use the PATH command in Step 4. Confirm that you used the Linux installer inside Ubuntu, not from a Windows Terminal window. |
Couldn’t install the Claude CLI on the remote: the installer produced no result [NO_INSTALL_RESULT] |
Claude Desktop did not receive a completion result while preparing Claude Code in WSL. Save open work and close any WSL terminals. In a new standard Terminal window, run wsl --shutdown. This stops running WSL sessions but does not remove the Ubuntu distribution or project files. Reopen Ubuntu, then retry the WSL → Ubuntu connection from Claude Desktop’s Code tab. This has resolved the error in testing, but is not guaranteed to resolve every cause. |
| Claude Code cannot find expected files or search is slow |
Move or clone the project under $HOME/projects, rather than working under /mnt/c/. |
| Login does not return to the terminal |
Use the login code displayed in the browser. If no browser opens, press c to copy the sign-in URL or run claude auth login. |
For other installation or sandbox errors, use Anthropic’s installation and login troubleshooting and sandbox documentation.
Wharton Computing is investigating this native-Windows issue. There is currently no supported Wharton Computing fix or estimated resolution date. The WSL2 route above is an unsupported, self-directed alternative.
If the installer finishes with setup notes that state that the native installation location is not in your 