Skip to content

Set up your dev environment — in the order that actually works.

Check the platforms you need to cover and the tools you want. This page assembles the install steps in dependency order, adds the prerequisites you did not know to ask for, and tells you why each one appeared. Every step ends in a check that names the output you should see, because it should work now is not a check.

Written for someone who has used a terminal and installed things before, but would rather not spend an afternoon working out why PATH is broken.

Step 00What you are installing

Pick your platforms, then your tools.

Platforms

Check every platform you need to document. Each one gets its own steps under its own heading, so printing this page makes one PDF for a whole team rather than one machine.

Tools

Prerequisites are added for you and labeled where they appear. Check a version manager and its runtime together and you get one step, not two.

Editor & version control

Programming languages

Web technologies

Containers

Databases

Step 01One tool at a time, in order

Install steps

Every command below is a single line even where the page wraps it. Enter comes only at the end. Where a step says to open a new terminal, it matters: a program reads your PATH once, when it starts.

Nothing is selected yet. Check a platform and a tool above and its steps appear here.

Xcode Command Line Tools

10 min

Added for you, needed by PHPPostgreSQLMySQL

Git lives inside it and Homebrew requires it, so on a Mac this comes before everything else.

macOS

  1. Run the install command below, then click Install in the dialog that appears.
  2. Wait. This is several hundred megabytes and takes 5 to 10 minutes on a good connection.
Shell
xcode-select --install
It looks like it hung

The progress bar shows no detail and can sit still for minutes at a time. That is normal. Leave it alone until the dialog closes on its own.

Done when: xcode-select -p prints a path ending in CommandLineTools or Xcode.app.

Homebrew

10 min

Added for you, needed by PHPPostgreSQLMySQL

Most of what follows on a Mac is one brew install away once this exists.

macOS

  1. Open brew.sh and copy the install command from the top of the page. Copy it from there rather than from here: it is long, and a version of it that got broken across two lines will fail in a way that is hard to read.
  2. Paste it into your terminal and press Enter. It asks for your password, and the password does not echo as you type. That is the terminal working correctly, not a dead keyboard.
  3. Read the "Next steps" block it prints at the end and run the two or three commands it lists. See the warning below.
  4. Open a new terminal.
Do not skip the Next steps block

This is the single most common Homebrew failure. The installer finishes, prints two or three shellenv commands, and if you close the window without running them, brew is command not found in every terminal you open afterward. Run what your own screen prints, not what any guide prints: the path differs between Apple Silicon (/opt/homebrew) and Intel (/usr/local).

Done when: brew --version prints a version number.

Linux

  1. Open brew.sh and copy the install command from the top of the page.
  2. Paste it into your terminal and press Enter.
  3. Run the commands from the "Next steps" block it prints at the end.
  4. Open a new terminal.
Do not skip the Next steps block

This is the single most common Homebrew failure. The installer finishes, prints two or three shellenv commands, and if you close the window without running them, brew is command not found in every terminal you open afterward. Run what your own screen prints, not what any guide prints: the path differs between Apple Silicon (/opt/homebrew) and Intel (/usr/local).

Done when: brew --version prints a version number.

VS Code

10 min

Added for you, needed by Git

This goes first because Git's Windows installer asks which editor you want, and it can only offer editors that already exist.

macOS

  1. Download from code.visualstudio.com, unzip, and drag Visual Studio Code.app into Applications.
  2. Open VS Code and press Cmd+Shift+P to open the command palette.
  3. Type shell command and choose Shell Command: Install 'code' command in PATH. Without this step the code command does not exist in your terminal.
  4. Open a new terminal.
Extensions worth naming

Search results are full of near-duplicates, so check the publisher: Python by Microsoft, C/C++ by Microsoft, ESLint and Prettier for JavaScript, Intelephense for PHP.

Done when: code --version prints a version number, three lines.

Windows

  1. Download from code.visualstudio.com. The default button gives you the User Installer, which needs no administrator rights.
  2. Run it. On the Select Additional Tasks screen, confirm Add to PATH is checked. It usually is, but not always.
  3. Open a new terminal after it finishes.
Extensions worth naming

Search results are full of near-duplicates, so check the publisher: Python by Microsoft, C/C++ by Microsoft, ESLint and Prettier for JavaScript, Intelephense for PHP.

Done when: code --version prints a version number, three lines.

Linux

  1. Download the .deb from code.visualstudio.com and install it, or add Microsoft's apt repository if you want it to update with the rest of your system.
  2. Open a new terminal.
Extensions worth naming

Search results are full of near-duplicates, so check the publisher: Python by Microsoft, C/C++ by Microsoft, ESLint and Prettier for JavaScript, Intelephense for PHP.

Done when: code --version prints a version number, three lines.

Git

Windows 20 min | macOS 10 min | Linux 5 min

Install this after your editor and before anything that clones a repository.

macOS

  1. Git ships inside the Command Line Tools, so it is probably already there. Run git --version. If a dialog appears offering to install, accept it.
  2. Set your name and email with the two commands below. Use the same email as your GitHub account.
  3. Point Git at VS Code and default new repositories to main, which is what the Windows installer does for you and macOS does not.
Shell
git config --global user.name "Your Full Name"git config --global user.email "you@example.com"git config --global core.editor "code --wait"git config --global init.defaultBranch main
If you clicked past the editor screen

Accepting the Vim default leaves you trapped in a full-screen editor with no visible way out the first time Git opens one. The exit is Esc, then :q!, then Enter. To fix it properly, re-run the installer and pick VS Code. Re-running is safe and preserves your other settings.

Done when: git --version prints a version number.

Windows

  1. Download the installer from git-scm.com and run it. It has roughly 14 screens. Four of them need a change; the rest are correct as they come.
  2. Choosing the default editor: change this from Vim to Use Visual Studio Code as Git's default editor. This is the most important screen in the installer.
  3. Adjusting the name of the initial branch: choose Override the default branch name and leave it as main, which is what GitHub expects.
  4. Adjusting your PATH environment: keep the recommended middle option.
  5. Choosing a credential helper: keep Git Credential Manager. It opens a browser to log into GitHub rather than asking for a password you do not have.
  6. Open a new terminal, then set your name and email with the two commands below.
PowerShell
git config --global user.name "Your Full Name"git config --global user.email "you@example.com"git config --global core.longpaths true
If you clicked past the editor screen

Accepting the Vim default leaves you trapped in a full-screen editor with no visible way out the first time Git opens one. The exit is Esc, then :q!, then Enter. To fix it properly, re-run the installer and pick VS Code. Re-running is safe and preserves your other settings.

Done when: git --version prints a version number.

Linux

  1. Install it from your package manager with the command below.
  2. Set your name and email with the two commands below. Use the same email as your GitHub account.
  3. Point Git at VS Code and default new repositories to main.
Shell
sudo apt update && sudo apt install gitgit config --global user.name "Your Full Name"git config --global user.email "you@example.com"git config --global core.editor "code --wait"git config --global init.defaultBranch main
If you clicked past the editor screen

Accepting the Vim default leaves you trapped in a full-screen editor with no visible way out the first time Git opens one. The exit is Esc, then :q!, then Enter. To fix it properly, re-run the installer and pick VS Code. Re-running is safe and preserves your other settings.

Done when: git --version prints a version number.

uv

10 min

Install this instead of installing Python directly. It fetches interpreters on demand, so a project needing a different Python is one command rather than a reinstall.

macOS

  1. Open docs.astral.sh/uv and copy the install command, or run brew install uv.
  2. Open a new terminal.
  3. Install an interpreter and start a project with the commands below.
  4. Point VS Code at the project's environment: open the project folder, press Cmd+Shift+P, run Python: Select Interpreter, and choose the one inside .venv.
Shell
uv python installuv init my-projectcd my-projectuv venv
Do not also install Python from python.org

Two Pythons on one machine is the top cause of it works in the terminal but my editor says the import is missing. uv's interpreters live somewhere your editor will not find on its own, which is why the Select Interpreter step above is a real step and not a nicety.

Done when: uv --version prints a version number.

Shell
uv run python -c "import sys; print(sys.executable)"

Prints the interpreter uv actually uses. That path is the one your editor needs to be pointed at, so it is worth reading rather than skipping.

Windows

  1. Open docs.astral.sh/uv and copy the install command, or run winget install astral-sh.uv.
  2. Open a new terminal.
  3. Install an interpreter and start a project with the commands below.
  4. Point VS Code at the project's environment: open the project folder, press Ctrl+Shift+P, run Python: Select Interpreter, and choose the one inside .venv.
PowerShell
uv python installuv init my-projectcd my-projectuv venv
Do not also install Python from python.org

Two Pythons on one machine is the top cause of it works in the terminal but my editor says the import is missing. uv's interpreters live somewhere your editor will not find on its own, which is why the Select Interpreter step above is a real step and not a nicety.

Done when: uv --version prints a version number.

Shell
uv run python -c "import sys; print(sys.executable)"

Prints the interpreter uv actually uses. That path is the one your editor needs to be pointed at, so it is worth reading rather than skipping.

Linux

  1. Open docs.astral.sh/uv and copy the install command.
  2. Open a new terminal.
  3. Install an interpreter and start a project with the commands below.
  4. Point VS Code at the project's environment: open the project folder, press Ctrl+Shift+P, run Python: Select Interpreter, and choose the one inside .venv.
Shell
uv python installuv init my-projectcd my-projectuv venv
Do not also install Python from python.org

Two Pythons on one machine is the top cause of it works in the terminal but my editor says the import is missing. uv's interpreters live somewhere your editor will not find on its own, which is why the Select Interpreter step above is a real step and not a nicety.

Done when: uv --version prints a version number.

Shell
uv run python -c "import sys; print(sys.executable)"

Prints the interpreter uv actually uses. That path is the one your editor needs to be pointed at, so it is worth reading rather than skipping.

nvm

15 min

Install this instead of installing Node directly, so a project needing a different Node version is a one-line change rather than a reinstall.

macOS

  1. Open github.com/nvm-sh/nvm and copy the install command from the README. Copy it from there rather than from here: the command has nvm's own version number in the URL, so a copy that sits in a guide installs an old nvm.
  2. Run it, then open a new terminal. The installer appends a block to your shell profile, and profiles are only read when a shell starts.
  3. Install Node and set it as your default with the commands below.
Shell
nvm install --ltsnvm use --ltsnvm alias default lts/*
On Windows, nvm is a different program

On macOS and Linux, nvm is nvm-sh/nvm. On Windows it is coreybutler/nvm-windows, a separate project by a different author, with different command syntax and an administrator requirement for nvm use. It also requires that you remove any existing Node install first. Skip that and you get the worst failure here: nvm use reports success while the old Node stays active, because it sits earlier on your PATH. You end up with a version manager that appears to do nothing at all.

Done when: nvm --version prints a version number.

Shell
node --version

Proves nvm actually put a Node on your PATH, which nvm --version alone does not tell you.

Windows

  1. Uninstall any existing Node.js first, through Settings → Apps. See the warning below. This is not optional.
  2. Download nvm-setup.exe from github.com/coreybutler/nvm-windows/releases and run it.
  3. Close every terminal and open a new one, this time as administrator: right-click your terminal in the Start menu and choose Run as administrator.
  4. Install Node and select it with the commands below. Note the syntax has no double dashes, which is where most Windows nvm instructions on the internet go wrong.
PowerShell
nvm install ltsnvm use lts
On Windows, nvm is a different program

On macOS and Linux, nvm is nvm-sh/nvm. On Windows it is coreybutler/nvm-windows, a separate project by a different author, with different command syntax and an administrator requirement for nvm use. It also requires that you remove any existing Node install first. Skip that and you get the worst failure here: nvm use reports success while the old Node stays active, because it sits earlier on your PATH. You end up with a version manager that appears to do nothing at all.

Done when: nvm --version prints a version number.

Shell
node --version

Proves nvm actually put a Node on your PATH, which nvm --version alone does not tell you.

Linux

  1. Open github.com/nvm-sh/nvm and copy the install command from the README.
  2. Run it, then open a new terminal.
  3. Install Node and set it as your default with the commands below.
Shell
nvm install --ltsnvm use --ltsnvm alias default lts/*
On Windows, nvm is a different program

On macOS and Linux, nvm is nvm-sh/nvm. On Windows it is coreybutler/nvm-windows, a separate project by a different author, with different command syntax and an administrator requirement for nvm use. It also requires that you remove any existing Node install first. Skip that and you get the worst failure here: nvm use reports success while the old Node stays active, because it sits earlier on your PATH. You end up with a version manager that appears to do nothing at all.

Done when: nvm --version prints a version number.

Shell
node --version

Proves nvm actually put a Node on your PATH, which nvm --version alone does not tell you.

Python

15 min

These are the steps for installing Python on its own. If you picked uv, you do not need them.

macOS

  1. Download the .pkg from python.org/downloads and run it.
  2. Open the installed folder in Applications and double-click Install Certificates.command. Skipping this produces an SSL error weeks later that is genuinely hard to trace back to here.
  3. Open a new terminal.
Add python.exe to PATH

This is the single most consequential checkbox in any Python setup. Miss it and every Python command fails with an error that says nothing about PATH. The recovery is painless once you know: re-run the installer, choose Modify, and enable it. No uninstall needed.

Done when: python3 --version prints a version number starting with 3.

Windows

  1. Download from python.org/downloads using the large button at the top.
  2. On the first installer screen, check Add python.exe to PATH before clicking anything else. It sits at the bottom of that screen and is unchecked by default. See the warning below.
  3. Finish the install and open a new terminal.
Add python.exe to PATH

This is the single most consequential checkbox in any Python setup. Miss it and every Python command fails with an error that says nothing about PATH. The recovery is painless once you know: re-run the installer, choose Modify, and enable it. No uninstall needed.

Done when: py --version prints a version number starting with 3.

Linux

  1. Python is almost certainly already installed. Check with python3 --version before installing anything.
  2. If the version is too old for what you need, add the deadsnakes PPA or use uv rather than replacing the system Python, which other parts of your OS depend on.
Add python.exe to PATH

This is the single most consequential checkbox in any Python setup. Miss it and every Python command fails with an error that says nothing about PATH. The recovery is painless once you know: re-run the installer, choose Modify, and enable it. No uninstall needed.

Done when: python3 --version prints a version number starting with 3.

Go

10 min

One installer, no version manager needed, and nothing to configure afterward.

macOS

  1. Download the installer from go.dev/dl and run it.
  2. Open a new terminal.
Ignore anything that tells you to set GOPATH

Modern Go needs no GOPATH setup at all. Guides that walk you through configuring it were written before modules and will send you in circles.

Done when: go version prints a version number.

Windows

  1. Download the .msi from go.dev/dl and run it.
  2. Open a new terminal.
Ignore anything that tells you to set GOPATH

Modern Go needs no GOPATH setup at all. Guides that walk you through configuring it were written before modules and will send you in circles.

Done when: go version prints a version number.

Linux

  1. Install the distribution package, or download the tarball from go.dev/dl and follow the instructions on that page.
  2. Open a new terminal.
Ignore anything that tells you to set GOPATH

Modern Go needs no GOPATH setup at all. Guides that walk you through configuring it were written before modules and will send you in circles.

Done when: go version prints a version number.

Rust

15 min

rustup is the official installer and it is also the version manager, so there is no decision to make here.

macOS

  1. Open rustup.rs and copy the install command.
  2. Run it and accept the default installation option.
  3. Open a new terminal.

Done when: rustc --version prints a version number.

Shell
cargo --version

cargo is the build tool and package manager, and it is what you will actually type day to day.

Windows

  1. Open rustup.rs and download rustup-init.exe.
  2. Run it. It checks for the MSVC build tools and offers to install them if they are missing. Accept: Rust cannot link a program on Windows without them.
  3. Open a new terminal.

Done when: rustc --version prints a version number.

Shell
cargo --version

cargo is the build tool and package manager, and it is what you will actually type day to day.

Linux

  1. Open rustup.rs and copy the install command.
  2. Run it and accept the default installation option.
  3. Open a new terminal.

Done when: rustc --version prints a version number.

Shell
cargo --version

cargo is the build tool and package manager, and it is what you will actually type day to day.

C++

Windows 45 min | macOS 10 min | Linux 5 min

There is no single thing called C++ to install. You install a compiler, and which one you get depends entirely on your platform. All three below build the same standard code.

macOS

  1. The compiler comes with the Xcode Command Line Tools, which are already in your list above.
  2. What you get is clang++. g++ also works, but on a Mac it is a shim for clang rather than GNU g++, which is worth knowing before you follow GCC-specific documentation.
  3. For anything past a single file, add CMake: brew install cmake.
On Windows, cl only works in the Developer Command Prompt

MSVC does not put itself on your ordinary PATH. Open a normal terminal, type cl, and you get not recognized from a compiler that installed perfectly. Use Developer Command Prompt for VS, a separate Start menu entry. This catches nearly everyone, so it is here in the install step rather than buried in troubleshooting.

Done when: g++ --version prints a version banner.

Windows

  1. From visualstudio.com/downloads, scroll to Tools for Visual Studio and download Build Tools for Visual Studio. You do not need the full IDE.
  2. In the installer, select the Desktop development with C++ workload. This is several gigabytes and takes a while.
  3. Tick C++ CMake tools for Windows in the same workload while you are there, rather than coming back for it later.
  4. When it finishes, open Developer Command Prompt for VS from the Start menu. See the warning below: this is not the same as your normal terminal.
On Windows, cl only works in the Developer Command Prompt

MSVC does not put itself on your ordinary PATH. Open a normal terminal, type cl, and you get not recognized from a compiler that installed perfectly. Use Developer Command Prompt for VS, a separate Start menu entry. This catches nearly everyone, so it is here in the install step rather than buried in troubleshooting.

Done when: cl prints a version banner.

Linux

  1. Install build-essential with the command below. This is g++, make, and the standard headers together.
  2. Add CMake at the same time if you will build anything past a single file.
Shell
sudo apt update && sudo apt install build-essential cmake
On Windows, cl only works in the Developer Command Prompt

MSVC does not put itself on your ordinary PATH. Open a normal terminal, type cl, and you get not recognized from a compiler that installed perfectly. Use Developer Command Prompt for VS, a separate Start menu entry. This catches nearly everyone, so it is here in the install step rather than buried in troubleshooting.

Done when: g++ --version prints a version banner.

Node.js

10 min

These are the steps for installing Node on its own. If you picked nvm, you do not need them, and on Windows following both leaves you worse off than following neither.

macOS

  1. From nodejs.org, take the LTS download, not Current. LTS is currently the Node 24 line.
  2. Run the .pkg and accept the defaults.
  3. Open a new terminal.
Never use sudo with npm install -g

It creates root-owned files inside your home directory, and every install you run afterward fails with permission errors that point at the wrong thing. If you have already done it, a version manager is the clean way out.

Done when: node --version prints a version number.

Shell
npm --version

npm comes with Node, so a Node that works and an npm that does not means the PATH is half set up.

Windows

  1. From nodejs.org, take the LTS download, not Current.
  2. Run the .msi. Leave Tools for Native Modules unchecked. Checking it opens a PowerShell window that downloads Chocolatey, Python, and Visual Studio Build Tools: twenty minutes or more, frequently fails, and rarely needed.
  3. Open a new PowerShell terminal and allow npm to run, using the command below. Windows blocks it by default.
PowerShell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedGet-ExecutionPolicy -Scope CurrentUser
Never use sudo with npm install -g

It creates root-owned files inside your home directory, and every install you run afterward fails with permission errors that point at the wrong thing. If you have already done it, a version manager is the clean way out.

Done when: node --version prints a version number.

Shell
npm --version

npm comes with Node, so a Node that works and an npm that does not means the PATH is half set up.

Linux

  1. Use the NodeSource repository or a version manager. The version in your distribution's own repository is usually several years old.
Never use sudo with npm install -g

It creates root-owned files inside your home directory, and every install you run afterward fails with permission errors that point at the wrong thing. If you have already done it, a version manager is the clean way out.

Done when: node --version prints a version number.

Shell
npm --version

npm comes with Node, so a Node that works and an npm that does not means the PATH is half set up.

PHP

Windows 40 min | macOS 10 min | Linux 10 min

PHP has no cross-platform version manager worth learning, so each platform is genuinely its own path. The Windows one is much longer than the others, and that is the real state of things rather than a gap in this guide.

macOS

  1. Apple removed PHP from macOS in Monterey, so there is nothing already on your machine to use.
  2. Run brew install php. Homebrew builds it with the common extensions already enabled, including PDO SQLite, so there is nothing to configure afterward.
  3. Open a new terminal.

Done when: php --version prints a version number.

Shell
php --ini

Shows which config file PHP actually loaded. A (none) there means it never found your php.ini, which is why an extension you enabled appears to be ignored. php -m lists what is enabled.

Windows

  1. Install the Visual C++ Redistributable from aka.ms/vs/17/release/vc_redist.x64.exe first, or PHP fails to start with a missing VCRUNTIME140.dll.
  2. From windows.php.net/download, find the Non Thread Safe box, which is the right one for command-line use, and take the Zip link inside it.
  3. Extract it to C:\php. Not Program Files: the space in the path and its permissions both cause trouble. Confirm php.exe sits directly in that folder rather than in a nested one.
  4. Copy php.ini-development to php.ini in the same folder.
  5. Open php.ini and uncomment the extensions you need by deleting the leading semicolon. Be careful with extension_dir = "ext": there is a similar-looking extension_dir = "./" a few lines above it, and uncommenting that one instead breaks every extension.
  6. Add C:\php to your user PATH, not the system PATH.
  7. Restart every terminal and your editor. A program only reads the PATH when it starts.

Done when: php --version prints a version number.

Shell
php --ini

Shows which config file PHP actually loaded. A (none) there means it never found your php.ini, which is why an extension you enabled appears to be ignored. php -m lists what is enabled.

Linux

  1. Install the distribution package with the command below.
  2. If you need a current PHP rather than whatever your distribution froze on, add the ondrej PPA instead and install from there.
  3. Open a new terminal.
Shell
sudo apt update && sudo apt install php-cli

Done when: php --version prints a version number.

Shell
php --ini

Shows which config file PHP actually loaded. A (none) there means it never found your php.ini, which is why an extension you enabled appears to be ignored. php -m lists what is enabled.

Docker

30 min

This one is late in the order on purpose: it is a large download, it wants a restart, and nothing before it needs it.

macOS

  1. Download Docker Desktop from docker.com and install it.
  2. Open it once and let it finish starting. The whale in the menu bar stops animating when it is ready.
Two things worth knowing

Docker Desktop requires a paid subscription at larger companies, so check before installing it on a work machine. On Apple Silicon, images built for x86 run under emulation and are noticeably slow: prefer arm64 images where a project offers both.

Done when: docker --version prints a version number.

Shell
docker run hello-world

Prints a paragraph starting Hello from Docker!. This is the check that counts: the version command works even when the engine behind it is not running.

Windows

  1. Download Docker Desktop from docker.com and install it.
  2. It installs WSL2 if you do not have it, which requires a restart. Save your work before starting.
  3. After the restart, open Docker Desktop and let it finish starting.
Two things worth knowing

Docker Desktop requires a paid subscription at larger companies, so check before installing it on a work machine. On Apple Silicon, images built for x86 run under emulation and are noticeably slow: prefer arm64 images where a project offers both.

Done when: docker --version prints a version number.

Shell
docker run hello-world

Prints a paragraph starting Hello from Docker!. This is the check that counts: the version command works even when the engine behind it is not running.

Linux

  1. Install Docker Engine following the instructions for your distribution at docs.docker.com/engine/install. Docker Desktop exists for Linux but the Engine is the usual choice.
  2. Add yourself to the docker group so you do not need sudo for every command, then log out and back in.
Two things worth knowing

Docker Desktop requires a paid subscription at larger companies, so check before installing it on a work machine. On Apple Silicon, images built for x86 run under emulation and are noticeably slow: prefer arm64 images where a project offers both.

Done when: docker --version prints a version number.

Shell
docker run hello-world

Prints a paragraph starting Hello from Docker!. This is the check that counts: the version command works even when the engine behind it is not running.

PostgreSQL

20 min

The default choice for most new work. Read the database note above first: the thing that goes wrong here is almost never the install.

macOS

  1. Run brew install postgresql@18. Pin the major version rather than installing bare postgresql, so a later brew upgrade cannot move your data directory out from under you.
  2. Start it. Homebrew installs the service without starting it, and this is a separate command that gets skipped constantly.
Shell
brew install postgresql@18brew services start postgresql@18

Done when: psql --version prints a version number.

Shell
psql -d postgres -c "select version();"

The version check only proves the client program exists. This one proves the server is running and accepting connections, which is the thing you actually need.

Windows

  1. Download the installer from enterprisedb.com. It bundles pgAdmin, which is a usable graphical client.
  2. Partway through it asks for a superuser password. Write it down now. There is no way to recover it later.
  3. Leave the port at 5432 unless you know something else is using it.

Done when: psql --version prints a version number.

Shell
psql -d postgres -c "select version();"

The version check only proves the client program exists. This one proves the server is running and accepting connections, which is the thing you actually need.

Linux

  1. Install and enable it with the commands below.
  2. On Debian and Ubuntu the install creates a postgres system user, and your first connection goes through it rather than through a bare psql.
Shell
sudo apt update && sudo apt install postgresqlsudo systemctl enable --now postgresqlsudo -u postgres psql

Done when: psql --version prints a version number.

Shell
psql -d postgres -c "select version();"

The version check only proves the client program exists. This one proves the server is running and accepting connections, which is the thing you actually need.

MySQL

20 min

Choose this when something downstream requires it, such as a hosting environment or a course specification. Otherwise PostgreSQL is the more common default.

macOS

  1. Run brew install mysql, then start it. As with PostgreSQL, starting it is a separate command.
  2. Run mysql_secure_installation. Homebrew installs MySQL with no root password at all, which is convenient and not a state to leave a machine in.
Shell
brew install mysqlbrew services start mysqlmysql_secure_installation

Done when: mysql --version prints a version number.

Shell
mysql -u root -p -e "select version();"

Prompts for the root password, then proves the server is up and your credentials work. A version check alone proves neither.

Windows

  1. Download the MySQL Installer from dev.mysql.com and run it.
  2. It asks for a root password. Write it down now.
  3. It asks about the authentication method. The current default is the stronger one and is correct for anything new. Pick the legacy option only if you already know the codebase you are connecting needs it.

Done when: mysql --version prints a version number.

Shell
mysql -u root -p -e "select version();"

Prompts for the root password, then proves the server is up and your credentials work. A version check alone proves neither.

Linux

  1. Install and secure it with the commands below.
  2. Many distributions ship MariaDB under the mysql command name. Check what mysql --version actually reports if you specifically need MySQL.
Shell
sudo apt update && sudo apt install mysql-serversudo systemctl enable --now mysqlsudo mysql_secure_installation

Done when: mysql --version prints a version number.

Shell
mysql -u root -p -e "select version();"

Prompts for the root password, then proves the server is up and your credentials work. A version check alone proves neither.

SQLite

5 min

No server, no port, no password, nothing to start. Usually there is nothing to install either: SQLite ships inside Python and inside PHP, and the command-line tool is already on macOS and most Linux systems.

macOS

  1. The sqlite3 command is already there. Skip to the check below.
The failure mode is not what you expect

Because there is no server, things do not fail with cannot connect. They fail by quietly creating an empty database somewhere you did not mean. A relative path in a script resolves against the folder your terminal is in, not the folder the script is in, so the same code appears to work in one terminal and finds nothing in another.

Done when: sqlite3 --version prints a version number and a date.

Shell
python3 -c "import sqlite3; print(sqlite3.sqlite_version)"

If you reach SQLite through a language rather than the shell, this is the check that matters. The PHP equivalent, php -r "new PDO('sqlite::memory:'); echo 'PDO SQLite OK';", proves in one command that PHP is installed, on the PATH, loading the right config file, and has the driver enabled.

Windows

  1. Run winget install SQLite.SQLite, or download the precompiled command-line tools from sqlite.org and add that folder to your PATH.
  2. Only do this if you want the standalone shell. If you are reaching SQLite through Python or PHP, you already have it.
The failure mode is not what you expect

Because there is no server, things do not fail with cannot connect. They fail by quietly creating an empty database somewhere you did not mean. A relative path in a script resolves against the folder your terminal is in, not the folder the script is in, so the same code appears to work in one terminal and finds nothing in another.

Done when: sqlite3 --version prints a version number and a date.

Shell
python3 -c "import sqlite3; print(sqlite3.sqlite_version)"

If you reach SQLite through a language rather than the shell, this is the check that matters. The PHP equivalent, php -r "new PDO('sqlite::memory:'); echo 'PDO SQLite OK';", proves in one command that PHP is installed, on the PATH, loading the right config file, and has the driver enabled.

Linux

  1. Run sudo apt install sqlite3 if the command is missing, which it usually is not.
The failure mode is not what you expect

Because there is no server, things do not fail with cannot connect. They fail by quietly creating an empty database somewhere you did not mean. A relative path in a script resolves against the folder your terminal is in, not the folder the script is in, so the same code appears to work in one terminal and finds nothing in another.

Done when: sqlite3 --version prints a version number and a date.

Shell
python3 -c "import sqlite3; print(sqlite3.sqlite_version)"

If you reach SQLite through a language rather than the shell, this is the check that matters. The PHP equivalent, php -r "new PDO('sqlite::memory:'); echo 'PDO SQLite OK';", proves in one command that PHP is installed, on the PATH, loading the right config file, and has the driver enabled.

Step 02Prove it, don't assume it

Check your work

Every check for what you selected, in one place. Run them in a terminal you opened after the last install finished.

macOS

ToolCommandYou should see
Xcode Command Line Toolsxcode-select -pa path ending in CommandLineTools or Xcode.app
Homebrewbrew --versiona version number
VS Codecode --versiona version number, three lines
Gitgit --versiona version number
uvuv --versiona version number
nvmnvm --versiona version number
Pythonpython3 --versiona version number starting with 3
Gogo versiona version number
Rustrustc --versiona version number
C++g++ --versiona version banner
Node.jsnode --versiona version number
PHPphp --versiona version number
Dockerdocker --versiona version number
PostgreSQLpsql --versiona version number
MySQLmysql --versiona version number
SQLitesqlite3 --versiona version number and a date

Windows

ToolCommandYou should see
VS Codecode --versiona version number, three lines
Gitgit --versiona version number
uvuv --versiona version number
nvmnvm --versiona version number
Pythonpy --versiona version number starting with 3
Gogo versiona version number
Rustrustc --versiona version number
C++cla version banner
Node.jsnode --versiona version number
PHPphp --versiona version number
Dockerdocker --versiona version number
PostgreSQLpsql --versiona version number
MySQLmysql --versiona version number
SQLitesqlite3 --versiona version number and a date

Linux

ToolCommandYou should see
Homebrewbrew --versiona version number
VS Codecode --versiona version number, three lines
Gitgit --versiona version number
uvuv --versiona version number
nvmnvm --versiona version number
Pythonpython3 --versiona version number starting with 3
Gogo versiona version number
Rustrustc --versiona version number
C++g++ --versiona version banner
Node.jsnode --versiona version number
PHPphp --versiona version number
Dockerdocker --versiona version number
PostgreSQLpsql --versiona version number
MySQLmysql --versiona version number
SQLitesqlite3 --versiona version number and a date
A version that does not match

A different number than you expected is usually fine: these steps ask for whatever is current, so your number will drift above any number written here. What is not fine is a command that is not found at all, which almost always means a terminal opened before the install finished. Close it and open another one before going anywhere near the troubleshooting below.

Step 03Search for what your screen says

When it goes wrong

Entries are titled with the text you are looking at, not the topic, because that is what you will search this page for. Nothing here is collapsed, so your browser's find can reach all of it.

Mac Can't install the software because it is not currently available

The download broke partway and left a half-installed folder behind. Remove it, then run the install again.

Shell
sudo rm -rf /Library/Developer/CommandLineTools
Mac Linux brew: command not found

The install worked and the shell does not know where to find it. You skipped the Next steps block, or ran it in a terminal you have since closed. Scroll back to the end of the install output and run the shellenv lines it printed, then open a new terminal. If the output is gone, re-running the installer prints it again and is safe.

Mac Building from source (this may take a while)

Homebrew ships prebuilt binaries only for recent macOS versions. On an older one it compiles instead, which can take an hour and can fail outright. It is not stuck. If you are several macOS releases behind, updating the OS is the real fix.

Win 'code' is not recognized as an internal or external command

The Add to PATH box was not checked during install. Re-run the installer and check it. Re-running is safe and keeps your settings.

Mac code: command not found

You skipped the command-palette step. Open VS Code, press Cmd+Shift+P, and run Shell Command: Install 'code' command in PATH, then open a new terminal.

Mac Win Linux Author identity unknown

You have not set user.name and user.email yet. Run the two config commands from this step. If commits work but do not show up as yours on GitHub, the email does not match a verified email on your GitHub account, which is a different problem with the same cause.

Win Filename too long

Windows has a path length limit that Node projects hit routinely. Turn on Git's long path support.

Shell
git config --global core.longpaths true
Mac Win Linux uv: command not found

The installer added uv to your PATH, and your terminal read its PATH when it started, which was before that happened. Open a new terminal.

Mac Linux which nvm returns nothing

This is not a broken install. nvm is a shell function, not a program on disk, so which cannot see it. Run command -v nvm instead: it prints nvm when things are working.

Win nvm install --lts fails on Windows

nvm-windows does not take double dashes. Use nvm install lts and nvm use lts. Any instructions you find with --lts were written for the Unix project.

Mac Linux node: command not found in a new terminal

No Node version is selected by default in a fresh shell unless you set a default alias. Run nvm alias default lts/* once and new terminals will pick it up.

Mac Linux Your editor cannot find Node but your terminal can

nvm loads from your shell profile, and not every process reads it. VS Code's integrated terminal usually does; a scheduled job or an app launched from Finder usually does not. Launching your editor from a terminal, rather than from the dock, is the quickest way around it.

Win Python was not found; run without arguments to install from the Microsoft Store

You typed python, and Windows ships a stub by that name that opens the Store. Type py instead, which is the launcher the installer sets up. To remove the stub permanently, go to Settings → Apps → Advanced app settings → App execution aliases and turn off python.exe and python3.exe.

Mac Linux It reports Python 2.x

You reached a system Python that is there for the operating system's own use. Type python3, not python. Do not replace or remove the system one.

Mac SSL: CERTIFICATE_VERIFY_FAILED

You skipped Install Certificates.command. Open the Python folder in Applications and double-click it now. Nothing else needs redoing.

Win 'cl' is not recognized as an internal or external command

You are in a normal terminal. MSVC only puts itself on the PATH inside Developer Command Prompt for VS. Open that from the Start menu and try again. Nothing is broken.

Mac Linux fatal error: 'iostream' file not found

On Linux you installed g++ alone rather than build-essential, so you have a compiler with no standard headers. Install build-essential. On macOS the Command Line Tools install went in partway. Run xcode-select --install again.

Win cannot be loaded because running scripts is disabled on this system

PowerShell blocks npm's launcher script by default. Run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned, then confirm it took with Get-ExecutionPolicy -Scope CurrentUser. On a managed work laptop the change is sometimes overridden silently, which is what that second command is for. If it will not stick, use Command Prompt instead, where npm works unchanged.

Win VCRUNTIME140.dll was not found

The Visual C++ Redistributable is missing. Install it from aka.ms/vs/17/release/vc_redist.x64.exe, then try again. Nothing about your PHP install needs redoing.

Win Loaded Configuration File => (none)

PHP is running but has not found a config file, so every extension you uncommented is being ignored. Confirm that php.ini sits in C:\php next to php.exe, and that it is named php.ini rather than php.ini.txt. Windows hides known extensions by default, so turn on File name extensions in Explorer's View menu to see the real name.

Mac Win Linux Cannot connect to the Docker daemon

Docker is installed and not running. On macOS and Windows, open Docker Desktop and wait for it to finish starting. On Linux, run sudo systemctl enable --now docker. If you see this on Linux only when you leave off sudo, you are not in the docker group yet, and the group change needs a full log out to take effect.

Mac Win Linux could not connect to server: No such file or directory

The server is not running. On macOS: brew services start postgresql@18, and brew services list tells you the current state. On Linux: sudo systemctl enable --now postgresql. On Windows, check Services for the postgresql entry.

Mac Linux database "yourname" does not exist

Running psql with no arguments tries to open a database named after your operating system user, which does not exist. The server is fine. Pass a database explicitly: psql -d postgres. This error sends people hunting for a broken server for far longer than it should.

Mac Win Linux port 5432 is already in use

Something already has that port: an older PostgreSQL install, or a Docker container you left running. docker ps settles the second one quickly. Stop whichever it is, rather than changing the port, unless you meant to run two.

Mac Win Linux Authentication plugin 'caching_sha2_password' cannot be loaded

This reads like a wrong password and is not. Your client, ORM, or driver is too old to speak MySQL's current authentication method. Update the client library first. Changing the server to the legacy method works and is the weaker fix.

Mac Linux Can't connect to local MySQL server through socket

The server is not running. On macOS: brew services start mysql. On Linux: sudo systemctl enable --now mysql.

Mac The wrong mysql runs

A mysql from an earlier install can sit ahead of the Homebrew one on your PATH, so you connect to a server you forgot about. which mysql settles which one you are actually running.

Any None of the above

Capture the whole terminal window rather than just the red text: the command you ran is usually more diagnostic than the error it produced. On macOS that is Cmd+Shift+4 then Space, on Windows Win+Shift+S. Say which step number and which platform you were on, and what the last thing that did work was.

Contact

A question about a post, a project, or working together — send it here. I try to reply within a couple of weekdays.

Required