Developer Environment Setup Checklist for New Machines

Overview

A good developer environment setup is not just a list of apps. It is a system that lets you move from a blank machine to productive work with minimal surprises. That means thinking in layers: operating system basics, identity and access, shells and terminals, language runtimes, package managers, editors, containers, browsers, debugging tools, and project-specific requirements.

The most reliable approach is to separate your setup into two parts:

• Core machine setup: tools and settings you want on every machine.
• Project setup: stack-specific dependencies, environment variables, local services, and repo-level scripts.

That separation matters. Core setup changes slowly and is worth documenting carefully. Project setup changes more often and should usually live in repository documentation, scripts, or automation.

Before you install anything, define the machine’s role. A frontend laptop, backend workstation, embedded development host, and IT admin machine have overlapping needs, but not identical ones. If you skip that decision, you often end up with tool sprawl, conflicting runtimes, and a machine that feels “mostly ready” without being reliably usable.

Use this sequence as your default order:

1. Secure the machine and update the OS.
2. Set up identity, credentials, and access.
3. Install terminal, shell, and package management basics.
4. Install version control and signing tools.
5. Install language runtimes and dependency managers.
6. Install editor, IDE, and essential extensions.
7. Set up containers, databases, and local service tooling.
8. Configure browsers, API tools, and debugging utilities.
9. Validate with a real project clone and test run.
10. Capture the setup in documentation or automation for next time.

If your team has not documented its local development setup yet, this checklist can also act as a developer onboarding checklist. New hires should not have to reverse-engineer a working laptop from chat messages and tribal knowledge.

Checklist by scenario

This section gives you a reusable dev machine checklist by common scenario. Start with the universal baseline, then add the sections that match your work.

Universal baseline for any new developer machine

• Apply operating system updates before installing stack tools. This reduces avoidable compatibility and security issues.
• Enable disk encryption, screen lock, and device tracking if your environment requires it.
• Install a password manager and avoid storing credentials in notes or browser tabs.
• Set up multi-factor authentication for code hosting, cloud providers, and package registries.
• Install Git and configure user name, email, default branch preference, line ending behavior, and credential helper.
• Generate and register SSH keys or configure your team’s preferred authentication method.
• Configure commit signing if your organization uses signed commits or tags.
• Install a terminal emulator and shell tools you will actually use every day.
• Install a package manager appropriate to the OS so future setup is scriptable.
• Choose a shell profile strategy and keep aliases, PATH changes, and exports organized.
• Install a code editor or IDE and sync settings only after you understand what gets imported.
• Install archive, search, and file utilities such as unzip support, fast grep tools, and diff tools.
• Set up browser profiles for work if you need isolation from personal extensions and sessions.

At this point, your machine is not project-ready, but it is prepared for consistent setup.

Web development setup checklist

• Install runtime managers for JavaScript or other web stack languages so you can switch versions cleanly.
• Install the required package managers used by your projects, and confirm lockfile behavior is understood.
• Install browser developer tools extensions only if they support your workflow; avoid overloading the browser.
• Set up local HTTPS support if your projects require secure cookies, service workers, or OAuth callback testing.
• Install API testing tools and export or import team collections as needed. If this is part of your workflow, pair your setup with a testing process like the REST API Testing Checklist for Developers and QA Teams.
• Install database clients for the systems you use often, but keep credentials separate from local notes.
• Set up Docker or local virtualization if your web stack depends on containers for databases, queues, or build environments.
• Verify browser debugging basics including network inspection, storage inspection, cookie behavior, and CORS troubleshooting. For recurring issues, keep a reference like the CORS Error Guide nearby.
• Install frontend quality tools such as formatters, linters, and test runners expected by your repositories.
• Validate a real local development setup by running a dev server, test suite, and production build at least once.

If you are choosing stack defaults for a fresh project, it also helps to settle language direction early. A team comparing typed versus untyped JavaScript can use a decision resource such as TypeScript vs JavaScript for New Web Projects before documenting local setup.

Backend and systems programming setup checklist

• Install compilers, build tools, and linkers required by your language and platform.
• Install language-specific toolchains for your backend or systems stack, and pin versions where possible.
• Configure environment variable management without committing secrets to repositories.
• Install container tooling if your services depend on reproducible builds or compose-based local environments.
• Install database and cache clients for local verification, not just production connectivity.
• Set up process monitoring and log viewing tools so local debugging is not limited to terminal scrollback.
• Confirm access to internal package registries, artifact stores, or VPN resources if your environment uses them.
• Install HTTP debugging utilities and keep an HTTP reference close by, such as the HTTP Status Code Reference for API Debugging and Monitoring.
• Verify test, build, and migration commands on a real service repository.

The key goal here is not merely compiling code. It is being able to build, run, inspect, test, and diagnose services locally with the same conventions the team expects in review and deployment.

Embedded and microcontroller development setup checklist

• Install vendor SDKs, compilers, and flashing tools required by your target boards.
• Install USB, serial, or device access drivers where applicable, and confirm permissions for device access.
• Set up serial terminal tools and save common baud rates or connection profiles.
• Install build system dependencies such as make, CMake, Python helpers, or board-specific package managers.
• Verify debugger integration for JTAG, SWD, OpenOCD, or vendor-specific tools if your workflow depends on them.
• Confirm udev or equivalent device rules so flashing does not require repeated manual work.
• Install documentation and data sheet access shortcuts if internet access may be limited during hardware work.
• Test with a known-good sample project that builds, flashes, and communicates over serial.

Embedded setups fail in subtle ways because they depend on both software and hardware assumptions. A machine that compiles firmware but cannot flash devices or attach a debugger is still incomplete.

Team onboarding and shared setup checklist

• Create one canonical setup document instead of maintaining conflicting setup notes across chat, wikis, and old repos.
• Define what is required versus optional so new teammates know the minimum path to first contribution.
• Prefer scripts over manual repetition for package installation, repo bootstrap, pre-commit hooks, and environment checks.
• Provide sample environment files with safe placeholders and clear variable descriptions.
• Document access dependencies early such as VPN, SSO groups, cloud roles, or registry permissions.
• Include a validation checklist: clone repo, install dependencies, run tests, start app, call API, open debugger, and create a test commit.
• Align setup with team process including branching and review conventions. If needed, pair this with Git Workflow Comparison and the Code Review Checklist for Small Teams and Fast-Moving Projects.

What to double-check

Most setup problems come from things that were installed but not validated. These are the areas worth checking before you consider a new laptop setup for developers complete.

Version alignment

Confirm that local runtime and compiler versions match project expectations. A machine can look healthy while quietly using the wrong Node, Python, Java, Go, or C toolchain. If your team supports multiple active projects, version managers are usually safer than system-wide installs.

Path and shell behavior

Make sure commands resolve from the expected locations. Duplicate package managers, conflicting shell startup files, and stale PATH entries are a common source of “works in one terminal but not another” bugs.

Git and repository defaults

Double-check line endings, file mode handling, ignored files, signing behavior, and credential helpers. These settings are easy to overlook and surprisingly expensive when they cause noisy diffs or failed pushes.

Secrets and certificates

Verify that your machine can authenticate to code hosting, package registries, cloud services, and internal APIs without exposing secrets in plaintext files. If local development uses self-signed certificates or internal CAs, test them in the browser and in command-line clients.

Container permissions and volume behavior

Docker and similar tools often appear installed correctly even when file permissions, networking, or bind mounts are wrong. Run a real containerized service before trusting the setup.

Editor automation

Check that formatting, linting, import organization, and test integration behave the same in the editor and the command line. Mismatches here create frustrating review noise. If your team works with SQL regularly, a shared formatting reference like the SQL Formatter Guide can help keep editor behavior aligned with review expectations.

Browser and API workflow

Open the local application, sign in if needed, inspect a request, review cookies or tokens, and test a failing request path. If your workflow includes token inspection or payload debugging, keep practical utilities close at hand rather than searching for them every time.

Common mistakes

A strong developer environment setup avoids a few predictable traps.

• Installing tools before documenting requirements. This leads to a machine full of experiments rather than a stable baseline.
• Relying on memory. If the process matters, write it down while it is fresh. Setup notes created after a successful install are usually incomplete.
• Syncing every old editor setting immediately. Imported settings can bring stale plugins, conflicting keybindings, and environment-specific paths.
• Using one machine for many stacks without isolation. Version managers, containers, and per-project configuration reduce conflicts.
• Skipping validation. “Installed” is not the same as “working.” Always build, run, test, and debug a real project.
• Ignoring security basics. A fast local development setup is not worth much if credentials, tokens, and signing keys are scattered across the machine.
• Treating onboarding friction as normal. Repeated setup confusion is usually a documentation or automation problem, not a people problem.
• Over-customizing too early. Start with reliable defaults, then add shortcuts after your workflow stabilizes.

The most durable local development setup is boring in a good way: predictable, scriptable, and easy for someone else to reproduce.

When to revisit

This checklist is most useful when you return to it regularly. Revisit your setup process before planning cycles, before onboarding a new teammate, after changing your main stack, or whenever team workflows shift. You should also review it after major editor changes, operating system upgrades, container tooling changes, authentication changes, or a move to new hardware.

A practical review cycle looks like this:

1. Run the checklist on a clean machine or VM once in a while to find undocumented assumptions.
2. Update the canonical setup document when a tool or workflow changes, not weeks later.
3. Remove obsolete steps so new developers do not install tools the team no longer uses.
4. Convert repeated manual actions into scripts for package install, repo bootstrap, and validation commands.
5. Add a final verification section that proves the machine is actually ready for daily work.

If you want one action to take today, make it this: create a short “first hour on a new machine” document for your team. Include the minimum tools, access requirements, one sample repository, one validation workflow, and one place to report setup friction. That single document often does more for developer productivity than another round of tool shopping.

A developer machine should not be a personal puzzle. It should be a dependable workspace that lets you write, run, debug, and review code with as little setup friction as possible. Keep the checklist close, trim it when tools change, and treat it as part of your engineering workflow—not a one-time chore.