sodcalculator

10 Tech How-To

Windows Developer Environment Setup: What It Fixes

Guide 10-30899 · Updated · Step by step

Setting up a dedicated Windows developer environment means configuring your machine with the right tools, package managers, and settings so you can write, build, and debug code without constant friction. This guide walks you through a clean, practical setup that fixes common problems like missing dependencies, inconsistent versions, slow terminal workflows, and the dreaded “it works on my machine” syndrome. You’ll end up with a reproducible, efficient setup that saves hours each week.

What You’ll Need

  • A Windows 10 or Windows 11 PC with at least 8GB RAM (16GB recommended) and 20GB free disk space.
  • Administrator access to install software.
  • An internet connection for downloads.
  • A code editor or IDE (Visual Studio Code is a popular choice, but any editor works).

Step-by-Step

  1. Enable Windows Subsystem for Linux (WSL2). Open PowerShell as Administrator and run: wsl --install. This installs WSL2 and the default Ubuntu distribution. Restart your PC when prompted. After reboot, set up a Linux username and password. WSL2 gives you a real Linux kernel, which fixes many path, permission, and package compatibility issues that plague native Windows development.
  2. Install a modern terminal. Open the Microsoft Store and install “Windows Terminal”. It provides tabs, split panes, and better rendering. Set it as your default terminal application in Windows Settings > Privacy & Security > For developers.
  3. Install a package manager. For Windows, install Chocolatey (or WinGet, which comes preinstalled on Windows 11). To install Chocolatey, run PowerShell as Administrator and execute: Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')). This centralizes software installs, making it trivial to update or replicate your setup.
  4. Install core development tools. Using Chocolatey, run: choco install git git-lfs vscode python nodejs-lts openjdk docker-desktop -y. This installs Git for version control, VS Code, Python, Node.js, Java, and Docker. These cover most development stacks. For .NET, run choco install dotnet-sdk -y.
  5. Configure Git. Open a terminal and set your identity: git config --global user.name "Your Name" and git config --global user.email "you@example.com". Then set the default branch to main: git config --global init.defaultBranch main. This avoids the “master” vs “main” confusion and ensures your commits are properly attributed.
  6. Set up SSH keys. Generate an SSH key for GitHub/GitLab: ssh-keygen -t ed25519 -C "you@example.com". Press Enter to accept the default location. Then add the public key (found in ~/.ssh/id_ed25519.pub) to your Git hosting account. This fixes authentication issues when cloning private repositories.
  7. Install language-specific package managers. For Node.js, npm is included. For Python, install pip (usually comes with Python) and then use pip install pipenv or pip install poetry for dependency management. For Java, use Maven or Gradle. These tools lock down dependency versions, preventing “works on my machine” due to floating versions.
  8. Configure VS Code. Open VS Code, go to Extensions (Ctrl+Shift+X), and install the “Remote – WSL” extension. This lets you open folders inside WSL2 directly. Also install language-specific extensions like “Python”, “ESLint”, “Prettier”, and “GitLens”. Set up your preferences in settings.json (File > Preferences > Settings) to enable format-on-save and consistent line endings.
  9. Set up Docker Desktop. After installation, open Docker Desktop and go to Settings > Resources > WSL Integration. Enable integration with your WSL2 distribution. This allows you to run containers from within Linux, fixing volume-mounting and performance issues.
  10. Create a project directory structure. Decide on a folder for your projects, e.g., C:\dev or ~/projects inside WSL. Stick to one structure. This avoids scattered code and makes backups easier.
  11. Test your setup. Create a simple test project: in WSL, run mkdir ~/test && cd ~/test && git init && echo "console.log('hello')" > index.js && node index.js. If you see “hello”, your environment works. Then commit it with git add . && git commit -m "initial".

Common Mistakes

  • Using PowerShell instead of WSL for commands. Many tools assume a Unix shell. Always use the WSL terminal for Linux commands; PowerShell for Windows-specific tasks.
  • Mixing line endings. Windows uses CRLF, Linux uses LF. Git can auto-convert if you set core.autocrlf true on Windows, but within WSL it’s better to set core.autocrlf input to avoid commits with spurious changes.
  • Installing everything globally. Use project-local package managers (like npm’s --save-dev or Python’s virtual environments) to avoid version conflicts.
  • Skipping the SSH key setup. You’ll hit authentication errors on every clone. Do it once, and it’s painless.
  • Not enabling WSL integration in Docker. If Docker volumes don’t mount correctly, this is usually why.

Tips

  • Use a dotfiles repository. Store your config files (.bashrc, .gitconfig, VS Code settings) in a GitHub repo. This makes migrating to a new machine trivial.
  • Learn basic Linux commands. You’ll be using grep, find, chmod, and ssh regularly. A quick online tutorial will pay off.
  • Keep your system updated. Run choco upgrade all -y weekly and sudo apt update && sudo apt upgrade -y inside WSL to get security fixes and compatibility improvements.
  • Use Windows Terminal profiles. Set up separate profiles for PowerShell, CMD, and WSL so you can switch with a keystroke.
  • Allocate enough RAM to WSL. If you have 16GB, give WSL 8GB via a .wslconfig file in your user folder. This prevents out-of-memory errors when running multiple containers.

Troubleshooting

  • WSL installation fails. Ensure virtualization is enabled in BIOS. Run dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart and dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart, then restart.
  • Command not found after installing with Chocolatey. Close and reopen the terminal. If still not found, check the installation path and add it to your PATH environment variable.
  • Git clone fails with permission denied. Verify your SSH key is added to the agent: ssh-add ~/.ssh/id_ed25519. Also check the key is added to your Git hosting account.
  • Docker containers can’t access the internet. Check Docker’s proxy settings in Docker Desktop. In corporate networks, you may need to configure HTTP_PROXY environment variables.
  • VS Code Remote-WSL fails to connect. Try “Remote-WSL: Rebuild WSL” from the command palette. Also ensure WSL is updated: wsl --update.
  • Node.js or Python not recognized in WSL. You may have installed them on Windows, but WSL is a separate system. Install them inside WSL using sudo apt install nodejs npm or the official installers for Linux.

Frequently Asked Questions

Do I really need WSL2? Can’t I just use Windows?

You can, but many open-source tools, deployment scripts, and package managers assume a Unix environment. WSL2 gives you a seamless Linux experience without a virtual machine, fixing path and permission issues that plague native Windows.

What’s the difference between Chocolatey and WinGet?

Both are package managers. Chocolatey has been around longer and has a larger repository, but WinGet is built into Windows 11 and is faster for simple installs. You can use either; the key is consistency.

How do I update all my dev tools at once?

With Chocolatey, run choco upgrade all -y. Inside WSL, use sudo apt update && sudo apt upgrade -y for system packages. For language-specific packages, use their respective tools (e.g., npm update -g).

Can I use this setup for mobile development?

Yes, but you’ll need to install Android Studio and Xamarin or Flutter. The WSL2 setup still helps with backend and build scripts. For iOS, you’ll need a Mac, but you can use cloud CI services.

Will this slow down my PC?

WSL2 uses a lightweight VM, which has some overhead, but modern hardware handles it fine. Docker can be memory-hungry; adjust limits in Docker Desktop settings. Overall, the efficiency gains outweigh any slowdown.

How do I back up my dev environment?

Version-control your dotfiles and project configuration files. For a full backup, use Windows File History or a cloud backup service. You can also export your WSL distribution with wsl --export.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →