Claude Code on Windows: WSL or Native?

Who this is for: Windows users deciding how to install Claude Code. This is a decision you make once at setup time; it is worth getting right.

The short answer

	Native Windows (PowerShell)	WSL (Linux inside Windows)
Setup effort	Low — same as any Windows app	Medium — one-time, ~20 minutes
Basic tasks (reading, summarising, editing)	Works well	Works well
Python tools (markitdown, pandas, marker)	Works, occasional friction	Works cleanly
Shell commands Claude writes internally	Sometimes fails or needs adaptation	Always works
Pandoc, uv, markitdown skills	Works, more setup steps	Works out of the box
Your files on C:\	Direct access	Accessible via `/mnt/c/`
Recommended for	Trying Claude Code, light use	Serious or regular research use

If you are unsure: start with native Windows. If you run into repeated tool failures or friction with Python scripts and shell commands, switch to WSL. The switch is not difficult and your files stay where they are.

Option A: Native Windows (PowerShell)

When this is enough

You mainly want to read documents, write summaries, edit drafts
You are not planning to use markitdown, marker, or pandas heavily
You want to get started quickly with minimal setup

Setup

If Claude Code is not yet installed, open PowerShell and run:

irm https://claude.ai/install.ps1 | iex

Close and reopen PowerShell after it completes.

Verify it works:

claude --version

Daily use: Open PowerShell, navigate to your project folder, launch Claude:

cd C:\Users\yourname\Documents\research\montaillou
claude

Known friction points on native Windows

Shell commands: Claude internally writes bash-style commands. On Windows it adapts to PowerShell, but not always perfectly. If Claude seems confused about how to run something, tell it explicitly:

> We are on Windows. Use PowerShell syntax for any shell commands.

Python and pip: Work on Windows but PATH setup can cause issues. If python3 is not recognised, try python instead. If pip is not found after installing Python, close and reopen PowerShell.

markitdown: Install with pip install "markitdown[pdf]" — the bare pip install markitdown installs without PDF support and will silently fail on PDF files. If you get errors after adding [pdf], try running PowerShell as Administrator.

uv: Works well on Windows — the install command from A6 is Windows-compatible.

Option B: WSL — Linux inside Windows

What WSL is

WSL (Windows Subsystem for Linux) runs a full Linux environment inside Windows. From the inside, it looks and behaves exactly like a Linux or Mac terminal. Claude Code running in WSL is identical to Claude Code on a Mac — all shell commands work, all tools install cleanly, no adaptation needed.

Your Windows files (on C:) are accessible from WSL at /mnt/c/Users/yourname/. You can work with them normally; the path is just different.

When WSL is worth it

You plan to use the full toolkit: markitdown, marker, pandas, pandoc
You want the /to-md, /convert-folder skills from A.markdown-central to just work
You are doing batch processing or corpus work
You hit repeated failures with shell commands in native Windows

Setup: enabling WSL

Step 1 — Enable WSL (requires Windows 10 version 2004+ or Windows 11):

Open PowerShell as Administrator (right-click PowerShell → "Run as administrator"):

wsl --install

This installs WSL and Ubuntu (the standard Linux distribution). It will ask you to restart your computer.

After restart, Ubuntu opens automatically and asks you to create a username and password. Choose anything — this is your Linux account, separate from your Windows login. Write it down; you will need it occasionally.

Step 2 — Verify WSL is working:

Open the "Ubuntu" app from the Start menu (or search for it). You should see a Linux terminal prompt like:

yourname@COMPUTER:~$

You are now in Linux.

Step 3 — Install Claude Code inside WSL:

curl -fsSL https://claude.ai/install.sh | bash

Close and reopen the Ubuntu terminal after this completes (the installer updates your PATH).

Step 4 — Install Python tools inside WSL:

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

Close and reopen the Ubuntu terminal, then:

uv python install 3.12
uv pip install "markitdown[pdf]" pandas openpyxl python-docx pymupdf requests

Step 6 — Install Pandoc inside WSL:

sudo apt-get install -y pandoc

Everything is now installed. Test:

claude --version
markitdown --version
pandoc --version

The native Claude Code install auto-updates in the background — no manual update step needed.

Working with your files in WSL

Your Windows files are at /mnt/c/ in WSL. Navigate to your research project:

cd /mnt/c/Users/yourname/Documents/research/montaillou
claude

Everything in that folder is accessible to Claude exactly as in native Windows — the path just starts with /mnt/c/ instead of C:\.

Tip — open WSL directly in a folder from Windows: In File Explorer, navigate to your project folder. Click the address bar, type wsl, press Enter. A WSL terminal opens already in that folder.

Tip — pin your research folder: Add a shortcut to your bash profile so you can jump there quickly. In the Ubuntu terminal:

echo 'alias research="cd /mnt/c/Users/yourname/Documents/research"' >> ~/.bashrc
source ~/.bashrc

Now typing research in any WSL terminal takes you directly to your research folder.

Setting up global Claude config in WSL

The global ~/.claude/ folder in WSL is separate from any Windows-side config. Set it up fresh inside WSL:

mkdir -p ~/.claude/commands
claude  # launch once to trigger authentication, then exit

Then create your global CLAUDE.md:

claude

> Create a global CLAUDE.md at ~/.claude/CLAUDE.md with a template
  for my identity and research preferences.

See A.concept.global-vs-local for what to put in it.

Switching between native Windows and WSL

You can have both installed. They are independent environments with separate installations of Claude Code, separate global configs, and separate Python packages.

If you set up both:

Use WSL for research work requiring tools
Use native PowerShell only if you need something Windows-specific

Most researchers settle on one and stick with it.

Troubleshooting

"wsl --install" fails or WSL won't start: Check that Windows is updated (Settings → Windows Update). WSL requires Windows 10 version 2004 (build 19041) or higher, or Windows 11.

"Ubuntu" app opens and immediately closes: The username/password setup may not have completed. Open PowerShell and type ubuntu — it will prompt you again.

Claude Code in WSL can't find my files: Your Windows files are under /mnt/c/, not C:\. Check with ls /mnt/c/Users/ to confirm the path.

markitdown or pandoc not found after install: Close and reopen the Ubuntu terminal. New tools added in a session are sometimes not available until the shell restarts.

Slow performance on files in /mnt/c/: This is a known limitation — reading Windows files from WSL has a small overhead. For very large corpora (thousands of files), consider working from within the WSL home directory (~/) and copying results back. For typical research use (tens or low hundreds of files) the overhead is negligible.

A3.code-basics-non-programmers — basic installation (covers Windows briefly)
A6.zero-coding-workflows — Python tools that work better in WSL
A.markdown-central — markitdown, marker, pandoc — the main reason to use WSL
A.concept.global-vs-local — setting up global config (separate in WSL vs Windows)