How to Install n8n for free on local machine using Docker Desktop

Overview

In this lesson, you will learn how to install n8n on your local machine using Docker Desktop for free. Docker provides an isolated, secure environment that simplifies managing dependencies and avoids compatibility issues common with direct installations. This tutorial will guide you step-by-step through installing Docker Desktop on macOS or Windows, setting up the necessary Docker volume, and running n8n as a Docker container on your local machine.

If you prefer a different installation method, you might also want to explore how to Install n8n via npm/Node.js, which is another popular approach.

Why Use Docker to Install n8n?

Before diving into the installation, it's important to understand why Docker is a great choice for hosting n8n locally:

• Isolation & Security: Docker containers run independently from your host system, reducing conflicts and enhancing security.
• Database Flexibility: By default, n8n uses SQLite, but with Docker you can easily configure other databases like PostgreSQL.
• Portability: Docker containers can be moved across different operating systems without compatibility issues.
• Simplified Setup: Docker bundles all dependencies, so you don’t have to worry about installing Node.js, npm, or other tools manually.
• Scalability & Control: You manage the resources and scaling of your n8n instance.

If you want a hassle-free experience without managing infrastructure, consider the n8n cloud service or learn more about the n8n Cloud Setup. But if you prefer full control and local hosting, Docker is the way to go.

Prerequisites

• A Mac or Windows machine (Docker Desktop is not supported on Linux).
• Administrative rights to install software.
• Basic familiarity with command line/terminal.

Note: Linux users should follow a separate process involving Docker Engine and Docker Compose. This tutorial covers Docker Desktop only.

Step 1: Install Docker Desktop

1.1 Download Docker Desktop

1. Visit the official Docker Desktop download page: https://docs.docker.com/desktop/
2. Choose the version matching your operating system (macOS or Windows).
3. For Mac users, select the correct chip version:
   • Apple Silicon (M1/M2 chips)
   • Intel Chip

1.2 Install Docker Desktop on macOS

1. Open the downloaded .dmg file.
2. Drag the Docker icon to your Applications folder.
3. Launch Docker Desktop from Applications or Spotlight.
4. When prompted, allow Docker to use your system password for necessary permissions.
5. Accept the recommended settings and skip optional surveys or sign-ups if desired.
6. Wait for Docker to start — you’ll see the Docker whale icon in your menu bar indicating it’s running.

1.3 Install Docker Desktop on Windows

1. Run the downloaded installer .exe file.
2. Follow the on-screen instructions, enabling required components like WSL 2 if prompted.
3. Restart your system if necessary.
4. Launch Docker Desktop and accept recommended settings.

For more detailed installation guidance, refer to the official Docker Desktop Documentation.

Step 2: Create a Docker Volume for n8n Data

Docker volumes persist data independently of containers, so your workflows and credentials remain safe even if the container is removed.

1. Open your terminal (macOS: Terminal app, Windows: PowerShell or Command Prompt).
2. Create a volume named n8n-data by running:

docker volume create n8n-data

3. Verify the volume has been created:

docker volume ls

You should see n8n-data listed.

Step 3: Run n8n Docker Container

Now you will pull the official n8n Docker image and run it as a container on your local machine.

1. Run the following command in your terminal:

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v n8n-data:/home/node/.n8n \
  n8nio/n8n

Explanation of parameters:

• -it: interactive terminal mode
• --rm: automatically remove the container when it stops
• --name n8n: names the container "n8n" for easy reference
• -p 5678:5678: maps port 5678 inside the container to port 5678 on your machine (the default n8n web UI port)
• -v n8n-data:/home/node/.n8n: mounts the previously created volume to persist data inside the container
• n8nio/n8n: the official n8n Docker image

What happens next?

• Docker will check if the image is available locally. If not, it will download the latest n8n image.
• After downloading, the container will start and n8n will be accessible at http://localhost:5678.

For more details on Docker installation and running containers, see the n8n Merge node documentation and the Docker official documentation.

Step 4: Access and Configure n8n

1. Open your web browser and go to:

http://localhost:5678

2. You will be prompted to set up the owner account for your n8n instance. This is a fresh installation inside the container, so settings from other local installs (e.g., npm installs) won’t carry over.

3. Fill in the form with your details:

• Name
• Email address (use a valid email if you want to receive updates)
• Opt in or out of product updates and surveys

4. Complete the onboarding steps as prompted, including any optional feature activation.

Once you have n8n running, you might want to continue with an n8n Interface Walkthrough to familiarize yourself with the UI and workflow creation.

Step 5: Managing Your n8n Docker Container

Start the container

If you stopped the container (using Ctrl+C or Docker Desktop UI), you can restart it with:

docker start n8n

Stop the container

To stop the running container:

docker stop n8n

Or via Docker Desktop UI by selecting the container and clicking Stop.

View running containers

docker ps

This lists all running containers and their resource usage.

Access Docker volumes and containers via Docker Desktop

• Open Docker Desktop.
• Navigate to Volumes to see n8n-data.
• Navigate to Containers to see the n8n container with CPU and memory usage.
• Use the UI to stop, start, and inspect containers.

Common Mistakes and Troubleshooting

• Docker Desktop not running: Ensure Docker Desktop is started before running any Docker commands.

• Port conflicts: If port 5678 is already in use, change the port mapping in the docker run command, e.g., -p 5679:5678.

• Volume missing or not mounted: Ensure you created the volume with the exact name n8n-data and mounted it correctly.

• Container exits immediately: Run with -it and without --rm to see error logs, e.g.:

  docker run -it --name n8n -p 5678:5678 -v n8n-data:/home/node/.n8n n8nio/n8n
  

• Permission issues: Running Docker commands may require administrator or sudo permissions.

• Docker image not found: Check your internet connection; Docker needs to download the image initially.

Additional Resources

• Official n8n Docker Installation Docs: https://docs.n8n.io/getting-started/installation/docker/
• Docker Desktop Documentation: https://docs.docker.com/desktop/

Quick Reference Cheat Sheet

By following the steps outlined above, you will have a fully functional n8n instance running locally within a Docker container. This setup is ideal for development, testing, or small-scale automation projects, providing you with a secure and portable automation platform.