How to Install n8n Locally on Any OS
I’ve set up n8n locally on everything from a Windows laptop to a Linux VM, and the fastest wins always came from choosing the right install method first.
How to Install n8n Locally on Any OS comes down to picking Docker for consistency or Node.js for a lightweight setup, then using the same core steps across Windows, macOS, and Linux.
Quick decision: pick the install method that matches your workflow
| Method | Best for | Main trade-off |
|---|---|---|
| Docker (recommended) | Reliable local dev, consistent across OS, easy upgrades | Docker adds overhead and can be slower on some Windows setups |
| Node.js (npm global) | Lightweight install, quick tinkering, no containers | More OS-specific dependency issues and PATH/version headaches |
| npx (one-off run) | Testing n8n fast without installing globally | Not ideal for long-term use and updates can feel unpredictable |
Prerequisites you should confirm before installing
- Admin rights on your machine (or permission to install packages).
- Stable network for pulling images or installing packages.
- A plan for persistence: if you want workflows and credentials to survive restarts, you must use a persistent data directory/volume.
Official n8n site: n8n
Option A: Install n8n locally with Docker (recommended)
Docker is the most OS-agnostic route: the same command works on Windows, macOS, and Linux. You also avoid many Node.js dependency conflicts.
Real challenge: Docker Desktop can feel heavy, and filesystem performance may be slower on Windows when you mount folders the wrong way.
Practical fix: use Docker volumes (not random host folders) for n8n data, and on Windows prefer WSL2-backed Docker for smoother performance.
Official Docker site: Docker
Run n8n with a persistent Docker volume
Open n8n in your browser at http://localhost:5678.
Keep it running (without --rm) and name the container
To stop/start later:
Upgrade safely with Docker
Real challenge: “Upgrading” by deleting containers can accidentally wipe your data if you didn’t persist it.
Practical fix: confirm your n8n data lives in a Docker volume, then pull the new image and recreate the container using the same volume.
Option B: Install n8n locally with Node.js (npm global)
This route is great if you want a lightweight local install, but it’s more sensitive to Node version changes and OS PATH issues.
Real challenge: many “n8n won’t start” problems trace back to mismatched Node versions or a global npm install landing outside your PATH.
Practical fix: keep Node.js on an active LTS release and verify node -v and npm -v work in the same terminal you’ll run n8n from.
Official Node.js site: Node.js
Install n8n globally
Open http://localhost:5678.
Where does n8n store your local data?
By default, n8n stores local state (workflows, credentials, encryption settings) in your user home directory under a hidden n8n folder. That’s convenient—but it also means you should back it up if you care about your local workflows.
Upgrade and uninstall (npm)
Option C: Run n8n with npx (fast test, no global install)
This is perfect when you just want to see n8n running locally in minutes.
Real challenge: npx can pull different versions over time, which can surprise you during repeat tests.
Practical fix: pin a version when you want repeatable behavior, and switch to Docker or global install when you commit to local usage.
Official npm site: npm
Pinning an example version:
OS-specific notes that prevent common local install failures
Windows
- Docker: if containers feel slow, use WSL2-based Docker and keep n8n data in a Docker volume.
- Node.js: if
n8nisn’t recognized, close/reopen your terminal, then verify global npm bin is in PATH. - Port conflicts: if 5678 is already used, change the mapped port with Docker (example below).
macOS
- Docker: works reliably, but keep an eye on CPU usage if you run many workflows at once.
- Node.js: if you use multiple Node versions, make sure the terminal session running n8n is on the expected version.
Linux
- Docker: best option when you want clean upgrades and easy resets.
- Permissions: if Docker commands require sudo, either use sudo or fix Docker group permissions (varies by distro policy).
First-run hardening for local n8n (small steps, big payoff)
Even on localhost, you’ll eventually paste API keys and connect SaaS accounts, so treat your local instance like it matters.
- Back up your data directory/volume before major upgrades.
- Use a consistent encryption key if you plan to move data between machines or containers later.
- Don’t expose localhost to the public internet unless you understand reverse proxies, auth, and firewall rules.
Troubleshooting: the issues you’ll actually hit
“Port 5678 is already in use”
Pick a different host port (like 5679) and map it to container port 5678, or stop the other service using 5678.
“n8n command not found” (Node.js install)
Your global npm bin directory is likely not in PATH for that shell. Restart the terminal and verify npm config get prefix points to a location your PATH includes.
Docker container starts, then exits
Check logs to see the exact error. Most early exits come from permissions on mounted directories or incompatible environment settings.
Advanced FAQ (long-tail, real-world local setups)
Can you run n8n locally without Docker on Windows?
Yes—install Node.js and run a global npm install. The main pitfall is PATH and Node version drift, so keep Node on LTS and verify the n8n command resolves in the same terminal session.
How do you keep workflows and credentials after a reboot?
Use persistence. With Docker, mount a named volume to the n8n data directory. With Node.js, back up your user home n8n folder regularly, especially before upgrades.
How do you run n8n on a different local port?
With Docker, change the host port mapping (for example, -p 5679:5678) and keep the container port at 5678. With Node.js, you’ll typically set the port via environment variables, but Docker port mapping is the cleanest local approach.
Is WSL2 required for Docker on Windows?
It’s not always required, but WSL2-backed Docker typically performs better for development workloads. If Docker feels sluggish or file watching behaves oddly, switching to WSL2 mode is a common fix.
How do you update n8n locally without breaking everything?
Back up first, then upgrade. With Docker, pull the new image and recreate the container while reusing the same persistent volume. With npm, update the global package and validate that your Node version is still compatible.
What’s the biggest mistake when installing n8n locally?
Running it once successfully and then assuming your data is safe. If you didn’t persist the data location (Docker volume or backed-up local folder), a reinstall or container cleanup can wipe workflows and credentials.
Can you use n8n locally for production-like automation?
You can build and test locally extremely well, but don’t treat a laptop instance like a production server. If you later expose it beyond localhost, you’ll need proper authentication, HTTPS via a reverse proxy, and a secure secret/encryption key strategy.
Conclusion
If you want the smoothest “works on any OS” install, start with Docker and a persistent volume, then upgrade by pulling the image and recreating the container with the same volume. If you prefer lightweight local tinkering, Node.js works well—just keep Node on LTS, confirm PATH, and back up your local n8n data before updates.