Before you can run n8n, Python scripts, or databases in isolated environments, you must install the runtime engine: Docker.
Many tutorials treat Docker installation as a trivial "Click Next" process. This is dangerous. Docker is not a simple application; it is a hypervisor manager that creates a Linux Virtual Machine (VM) on your host operating system. Understanding this architecture is key to troubleshooting when things go wrong.
Here is the rigorous, architectural guide to installing Docker Desktop correctly on macOS and Windows.
The Architecture (Mac)
MacOS is Unix-based, which makes it closer to Linux than Windows is, but it still cannot run Linux binaries (containers) natively. Docker Desktop on Mac uses the Apple Hypervisor framework to run a lightweight Linux VM in the background.
Step 1: Select the Correct Architecture
⚠️ Most Common Failure Point: You must download the binary compiled for your specific CPU instruction set.
- Apple Silicon (M1/M2/M3/Pro/Max): You rely on the ARM64 architecture. Downloading the Intel version will force your Mac to use "Rosetta 2" translation, which creates massive performance overhead and instability for Docker.
- Intel Chip: You rely on the x86_64 architecture.
Step 2: Installation & Privileges
- Open the .dmg file.
- Drag the Docker icon to the Applications folder.
- Critical Step: Double-click Docker to start it. It will ask for your system password.
Why? Docker needs to install Privileged Helper Tools. These are networking components that allow the container (inside the VM) to talk to your macOS host ports (e.g., mapping port 5678). You must allow this.
Step 3: Resource Allocation (The Hidden Bottleneck)
By default, Docker might claim too much or too little RAM.
2. Memory: Assign at least 4GB (ideally 8GB if you have 16GB+ total)
3. CPUs: Assign at least 2
4. Swap: Keep default
The Architecture (Windows)
Windows uses the NT Kernel, which is fundamentally incompatible with Linux containers. Historically, Docker used a heavy VM (Hyper-V). Today, the gold standard is WSL 2 (Windows Subsystem for Linux 2).
WSL 2 runs a real Linux kernel alongside the Windows kernel using lightweight virtualization. This provides near-native performance.
Step 0: Prerequisites (BIOS/UEFI)
Before installing software, you must ensure your hardware allows virtualization.
2. Go to the Performance tab > CPU
3. Look for Virtualization: Enabled
If Disabled: You must restart your computer, enter BIOS (F2 or Del), and enable Intel VT-x or AMD-V.
Step 1: Install Docker Desktop
- Download the installer from Docker.com.
- Run the installer.
- Critical Checkbox: Ensure "Use WSL 2 instead of Hyper-V" is checked.
Why? Hyper-V is the legacy backend. It is slower and reserves system RAM even when containers aren't running. WSL 2 is dynamic and efficient.
Step 2: The WSL Update (Common Error)
During installation, Docker might prompt you that "WSL 2 installation is incomplete."
2. Run: wsl --update
3. Run: wsl --shutdown (to restart the subsystem)
Step 3: Verification
2. Wait for the engine starting status (whale icon) to turn Green
Regardless of your OS, you must verify that the engine can actually pull images from the registry and spin up a container.
Open your terminal (Terminal.app on Mac, PowerShell on Windows) and run:
The Physics of what just happened:
- Client: Your terminal sent a request to the Docker Daemon (background service).
- Check: The Daemon checked local storage for an image named hello-world.
- Pull: It didn't find it, so it connected to Docker Hub (cloud) and downloaded the layers.
- Run: It created a new container process, executed the script inside, streamed the text output to your terminal, and then shut down.
✓ Success: If you see the message "Hello from Docker!", your engineering foundation is solid. You are ready to install n8n or any other containerized service.