Windows Developer Environment Setup Guide: WSL, Git, PowerShell, and Package Managers

Overview

A modern Windows development machine usually combines native Windows applications with command-line and Linux-based tooling. Windows Terminal provides a consistent interface, PowerShell handles Windows administration and automation, Git manages source control, and WSL2 supplies a Linux environment for projects that depend on Linux commands or services.

The goal is not to make Windows behave exactly like another operating system. The goal is to decide where each task belongs and document the boundary. For example, you might keep your editor and browser on Windows, run Git and project commands in either PowerShell or WSL, and use a package manager to install repeatable command-line tools.

Before changing anything, record the current state of the machine. Note the Windows edition and build, available disk space, whether virtualization is enabled, existing Git installations, active PowerShell profiles, and important environment variables. This small inventory helps prevent duplicate installations and makes future troubleshooting easier.

Use this guide as a baseline rather than a rigid prescription. A frontend developer, API engineer, systems administrator, and data professional may need different runtimes and services. Install the smallest useful foundation first, then add tools as a project requires them.

Checklist by scenario

For a general Windows development setup

• Update the operating system deliberately. Apply pending updates during a planned maintenance window, especially before configuring virtualization, drivers, or system-wide development tools.
• Install Windows Terminal. Use separate profiles for PowerShell and any installed Linux distributions. Keep profile names clear so commands are run in the intended environment.
• Install Git for Windows. Confirm that git --version works in the shell you plan to use. Configure your name, email, default branch preference, credential method, and line-ending behavior according to your team’s conventions.
• Choose one primary package-management path. Windows Package Manager, commonly used through winget, is a practical system-level option. Chocolatey and Scoop can also be useful, but mixing several package managers for the same application makes ownership and upgrades harder to understand.
• Set up an editor and source-control integration. Verify that the editor opens the correct project directory and uses the intended Git executable, shell, formatter, and language runtime.
• Test the basics. Create a temporary folder, initialize a repository, make a commit, clone it into a second location, and remove the test files when finished.

For a WSL2-based workflow

• Check prerequisites. Confirm that hardware virtualization is enabled and that your Windows installation supports the WSL features you need. If the machine is managed by an organization, check whether virtualization settings are controlled centrally.
• Install or enable WSL using the supported Windows method. A common starting command is wsl --install, but the exact available options can vary by Windows version and administrative policy. Read the command output and restart when requested rather than repeating the installation blindly.
• Choose a distribution intentionally. Use a distribution that matches your project documentation or team environment. Avoid installing several distributions until you understand how files, packages, and credentials are separated between them.
• Update packages inside Linux. WSL distributions have their own package databases and system files. Installing a Windows package does not automatically install its Linux equivalent.
• Choose a project location. Projects stored inside the Linux filesystem are often a sensible default for Linux-first command-line workflows. Projects stored under Windows-mounted paths can be convenient for shared access, but file behavior and performance may differ by workload.
• Verify interoperability. Test editor access, Git authentication, SSH keys, port forwarding, environment variables, and any required local database or container service before beginning a major project.

For a PowerShell-centered workflow

• Separate built-in commands from custom functions. Keep reusable aliases, functions, completion settings, and prompt changes in a documented PowerShell profile rather than entering them manually every session.
• Use explicit paths in scripts. Resolve the script directory and use predictable relative paths where possible. This reduces failures caused by launching a script from a different working directory.
• Make scripts inspectable. Add strict error handling where appropriate, return meaningful exit codes, and avoid hiding command output that is useful during diagnosis.
• Test permissions. Run ordinary development commands as a standard user unless elevation is specifically required. If a script needs administrator privileges, make that requirement clear.
• Keep a small utility library. Store trusted scripts for tasks such as finding processes, checking ports, reading environment variables, and cleaning temporary files. The PowerShell Developer Productivity Toolkit can be used as a reference for building a maintainable command set.

For web, API, or data development

• Install only the runtimes required by the project, such as a language runtime, package manager, database client, or container tool.
• Prefer project-local dependency manifests and lockfiles over undocumented global packages.
• Record required ports, environment variables, service startup commands, and test commands in the project documentation.
• Keep secrets out of repositories, shell history, screenshots, and browser-based utilities. For related JSON, SQL, regex, JWT, and encoding workflows, review the Windows developer tools guide.

What to double-check

PATH order: Run where.exe git in PowerShell and which git in WSL to see which executable is being used. Multiple installations can produce confusing version differences.

Shell context: A command that works in PowerShell may not work in Bash, and a package installed inside WSL is not necessarily available to Windows applications. When troubleshooting, record the shell, current directory, command, and reported version.

Line endings and file permissions: Git settings, editor settings, and cross-platform projects can interact in surprising ways. Choose a repository convention and test it with a small file before applying broad changes.

Environment variables: Keep machine-wide values, user values, project values, and secrets conceptually separate. Restart terminals after changing persistent variables, and confirm the value in the process that actually runs the application.

Authentication: Test both HTTPS and SSH workflows if your projects use them. Confirm which credential helper or SSH agent is active, and do not copy private keys between environments without a clear reason.

Storage and backups: Development environments can consume substantial disk space through package caches, build output, virtual machines, and container images. Know where those files live and include important configuration or scripts in a backup plan.

Common mistakes

• Installing everything globally: Global tools can be useful, but project-specific dependencies should normally be declared with the project so another developer or a build system can reproduce them.
• Using several package managers without a plan: If the same tool is installed by winget, Chocolatey, and Scoop, upgrades may target different copies. Choose an owner for each installation and record it.
• Mixing Windows and WSL files casually: Moving a project between filesystems without understanding permissions, watchers, or path conventions can create slow builds and confusing behavior.
• Editing PATH manually without documentation: Long, duplicated PATH entries are difficult to audit. Prefer installers and package managers that can manage paths, and document any manual additions.
• Ignoring the current shell: A successful version check does not prove that the application, editor, task runner, or CI script uses the same executable.
• Skipping a recovery plan: Keep installation notes, profile files, setup scripts, and project bootstrap instructions somewhere separate from the machine being configured.

When to revisit

Revisit this checklist before a seasonal planning or maintenance cycle, when changing teams, and whenever your workflow changes substantially. It is especially useful before upgrading Windows, moving from a native workflow to WSL2, replacing a development machine, adopting a new package manager, or introducing a new runtime.

Do a short review when a command suddenly resolves to a different version, builds become slower, ports conflict, authentication fails, or an editor cannot find a runtime that works in the terminal. These symptoms often point to path order, shell context, duplicated installations, or a changed project configuration rather than a broken application.

For a practical refresh, follow this sequence:

1. Export or document your important shell profiles, Git settings, package lists, and project setup commands.
2. Remove obsolete tools only after confirming that no active project depends on them.
3. Check versions and executable locations from every shell you use.
4. Rebuild one small test project or clone a repository to verify Git, dependencies, editor integration, and runtime behavior.
5. Update the setup notes with anything that required a workaround.

A maintainable Windows developer environment is a living part of your workflow. Keep its responsibilities clear, minimize duplicate tools, and leave enough documentation that the next reset—or the next major workflow change—becomes a controlled task rather than a guessing exercise. For broader browser-based utilities that support debugging and web work, the Windows web development reference is a useful companion.