How to Set Up a Development Environment From Scratch

“It works on my machine” is the most expensive sentence in software. It usually means 2 developers have different versions of a language, a missing environment variable or a database configured by hand 18 months ago. The result is lost afternoons, flaky onboarding and bugs that only appear in production.

A good development environment fixes that. It’s fast to set up, the same for everyone on the team and easy to rebuild when your laptop dies. This guide walks through setting one up from scratch on macOS, Windows or Linux, in the order that avoids rework.

What a development environment includes

A development environment is the set of tools and configuration you use to write, run, test and debug code locally. The main layers are:

The guiding principle: install as little as possible globally, and capture everything project-specific in files that live in the repository.

Set up the basics: OS, terminal, Git and editor

These 4 steps are installed once per machine and shared by every project you work on.

Step 1: Prepare your operating system

macOS: Install the Xcode Command Line Tools (xcode-select --install), then Homebrew, the most common package manager for macOS. Use Homebrew for Git, your shell tools and anything else you need system-wide.

Windows: For most web and backend work, install the Windows Subsystem for Linux (WSL). Microsoft’s docs say running wsl --install in an administrator PowerShell enables the required features, sets WSL 2 as the default and installs Ubuntu, and it requires Windows 10 version 2004 or later, or Windows 11. Keep your code inside the Linux file system for better performance, and use winget for Windows apps such as your editor and terminal.

Linux: Update your system packages, then install build essentials (compilers and headers) through your distribution’s package manager.

If you’re still choosing hardware, our guide on how to choose a laptop covers the trade-offs.

Step 2: Set up your terminal and shell

You’ll spend hours a day here, so make it comfortable:

• Pick a modern terminal: Windows Terminal on Windows, iTerm2 or the built-in Terminal on macOS, or your distribution’s default on Linux.
• Choose a shell: zsh is the default on macOS; bash is common on Linux. Either is fine.
• Add a few productivity tools: a better prompt that shows your Git branch, fuzzy search for command history, and modern replacements for common commands if you like them.
• Keep your dotfiles in a Git repository so you can restore your shell config, aliases and editor settings on a new machine in minutes.

Don’t over-customize on day 1. Add tools when you feel a specific pain.

Step 3: Install and configure Git

Install Git through your package manager, then set your identity:

git config --global user.name "Your Name" git config --global user.email "you@example.com" git config --global init.defaultBranch main

Next, create an SSH key for your Git host. GitHub’s documentation recommends generating an Ed25519 key with ssh-keygen -t ed25519 -C "you@example.com", setting a passphrase, adding it to the ssh-agent and then adding the public key to your account. Turn on multi-factor authentication for your Git hosting account too.

New to Git? Our guide to Git for beginners covers the commands you’ll use daily.

Key takeaway: Install only the basics globally: package manager, terminal, Git and editor. Everything that differs between projects, such as language versions and databases, belongs in per-project config so it can be reproduced.

Step 4: Install and configure your editor

VS Code and JetBrains IDEs are the most common choices; Neovim and others are popular with developers who prefer the keyboard.

Set up these essentials:

• Language extensions for the languages you use (syntax, IntelliSense, debugging).
• Formatter and linter integration that runs on save, using the project’s config, not your personal preferences.
• EditorConfig support so indentation and line endings follow the repository’s .editorconfig.
• Settings sync through your editor account or dotfiles.
• Remote development support if you use WSL, SSH hosts or containers. VS Code’s Dev Containers extension, for example, opens a project inside a container defined by the repository.
• An AI coding assistant, if your company allows one. See our guide to AI coding assistants for where they help and where to be careful.

Install languages with version managers

This is the step that prevents most “works on my machine” problems. Never rely on a system-installed language version for project work. Use a version manager so each project can pin its own version.

Options: - Multi-language managers such as mise or asdf read a .tool-versions file (or their own config) and install the right versions of Node.js, Python, Ruby, Go, Java and more per project. - Language-specific managers such as nvm for Node.js, pyenv or uv for Python, rustup for Rust and SDKMAN! for Java.

Good practice: - Commit the version file (for example .tool-versions, .nvmrc or .python-version) to the repository. - Use long-term support releases for production work. The Node.js project, for example, says production applications should use only Active LTS or Maintenance LTS releases. - Use isolated dependency environments: project-local node_modules, Python virtual environments, and lock files committed to the repository.

Choosing between languages? See our Python vs JavaScript comparison.

Use containers for services and full environments

Containers make the rest of your stack reproducible.

Level 1: Services in containers. Run databases, caches and queues (PostgreSQL, Redis and similar) with Docker Compose instead of installing them on your machine. A compose.yaml file in the repository means everyone runs the same versions with one command. If containers are new to you, start with what Docker is.

Level 2: The whole environment in a container. The Development Container specification uses a devcontainer.json file to describe a complete development environment: base image, language tools, extensions, ports and setup commands. Tools that support it include the VS Code Dev Containers extension, the open-source dev container CLI and GitHub Codespaces. New teammates open the repository and get a ready environment, without installing runtimes locally.

Make the project reproducible

Your environment is only reproducible if the repository captures it. Commit:

• Tool version files (.tool-versions, .nvmrc, .python-version).
• Lock files for dependencies.
• .env.example listing every environment variable with safe placeholder values. Never commit real secrets; keep them in .env files listed in .gitignore or in a secrets manager.
• compose.yaml for local services and devcontainer.json if you use dev containers.
• A single setup command such as make setup or a scripts/setup file that installs dependencies, seeds the database and runs a smoke test.
• Formatter, linter and pre-commit hook configs so code quality checks run the same for everyone.
• A README quick start that works on a clean machine. Our guide to writing technical documentation includes a README template.

Test it: ask a new teammate to set up from the README alone, and fix every place they get stuck.

Security basics for your dev machine

• Turn on full-disk encryption and a screen lock.
• Use a password manager and multi-factor authentication for Git hosting, cloud consoles and package registries. Passkeys are worth enabling where supported.
• Keep secrets out of code, shell history and screenshots.
• Install packages and editor extensions only from trusted publishers.
• Keep your OS, editor and tools updated.

Our guide to secure coding best practices covers the code side.

Where to start: a 1-day setup plan

1. Morning: OS updates, package manager, terminal, shell and dotfiles repository.
2. Late morning: Git, SSH key, Git host login with multi-factor authentication.
3. Lunch break: Editor, extensions and settings sync.
4. Afternoon: Version manager and the language versions your first project needs.
5. Late afternoon: Docker or another container runtime, then clone the project and run its setup command.
6. End of day: Run the tests. Anything you had to figure out manually goes into the README or setup script.

Conclusion

A good development environment is boring in the best way: it’s quick to set up, matches your teammates’ and can be rebuilt from scratch without drama. Install the basics globally, pin language versions per project with version managers, run services in containers and commit the configuration that makes it all reproducible. When the setup is captured in the repository, onboarding takes hours instead of days, and “works on my machine” stops being an excuse. Teams that want to go further can build on this with platform engineering. For more developer terms, see our glossary.

Sources

• Microsoft Learn: Install WSL — wsl –install behavior and Windows version requirements
• GitHub Docs: Generating a new SSH key and adding it to the ssh-agent — Ed25519 key generation
• Development Containers: Supporting tools and services — devcontainer.json specification and supporting tools
• VS Code Docs: Developing inside a Container — Dev Containers extension
• Node.js: Previous releases — guidance to use LTS releases in production