Before you start
You need Docker. Docker Desktop on Mac, Windows or Linux includes Docker Engine and Docker Compose, which is what n8n's Docker page assumes. The Compose route asks for Docker Engine with Compose v2, so docker compose version should print a version, and n8n says its stack needs at least 4 GB of RAM and 2 vCPUs.
On Windows, n8n points you to WSL with Docker Desktop's WSL2 backend. Whether self-hosting suits you at all, and what the license allows, is covered in what is n8n. In short, running it for your own business is fine, and hosting it so your clients build their own workflows is not.
Three ways to start n8n in Docker
n8n's install options list a one-line setup, Docker Compose, npm, plain Docker and cloud providers. The one-line setup page says the old npm route stops working for fresh installs from n8n 3.0, which is distributed only through Docker. That version is in early access now, and its announcement puts the stable release in early December. Existing npm installs keep working.
The README's quick start gives the one-line script and a two-command Docker run side by side. The Docker page itself marks the plain run as outdated and points to Compose, so treat the run command below as a way to try n8n out.
n8n 2.0
A major release with breaking changes, so read the notes before you jump a major version.
Source: n8n Docs: Release notes (read November 5, 2026)
One command to self-host
n8n posts the one-line setup, n8n Assistant included, with
--upgradefor an instance you already run.Source: n8n.io on X: one command to self-host n8n, 21 August 2026 (read November 5, 2026)
n8n 3.0 in early access
Self-hosted n8n runs on Docker, and npm installs are no longer supported. The stable release is due in early December.
Source: n8n Blog: Introducing n8n 3.0 (read November 5, 2026)
| Way | What you get | n8n says |
|---|---|---|
| docker run | One container with a data volume | The docs page is marked outdated and recommends Docker Compose |
| One-line setup | A script that writes a compose.yml and a .env, then starts n8n with SQLite | The built-in SQLite database and bundled sandbox suit testing, and production wants Postgres |
| Docker Compose | The same stack as files you keep and edit, with Postgres as an option | The recommended route, at least 4 GB of RAM and 2 vCPUs |
Run n8n with docker run
The command below is n8n's own quick start from its Docker page. Replace both timezone placeholders with your timezone. The --rm flag removes the container when it stops, which is why the data has to live on the volume.
docker volume create n8n_data
docker run -it --rm \
--name n8n \
-p 5678:5678 \
-e GENERIC_TIMEZONE="<YOUR_TIMEZONE>" \
-e TZ="<YOUR_TIMEZONE>" \
-e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
-v n8n_data:/home/node/.n8n \
n8nio/n8n- Install Docker and make sure the Docker daemon is running.
- Create the volume and start the container with the commands above, with your timezone in both places.
- Open
http://localhost:5678and complete the owner setup. The first person to finish it becomes the owner. - Build a small workflow, stop the container and run the same command again. The workflow is still there, because it lives on the volume and not in the container.
- To keep n8n running in the background, add
-d, as n8n does in its own update steps.
The way n8n recommends: the one-line setup and Compose
The one-line setup checks that Docker is running, creates an n8n folder in your current directory, writes compose.yml, searxng-settings.yml and a .env with generated secrets, then downloads and starts n8n and its sandbox services. Open the URL it prints. Your data sits in ./n8n and in the Docker volume n8n-data.
The service that is n8n itself is short. In the Compose file the script downloads, it pulls docker.io/n8nio/n8n:${N8N_VERSION}, publishes 5678:5678, reads .env and mounts n8n-data at /home/node/.n8n. The other services support n8n Assistant and run Code node tasks. Only n8n's own port should face the internet.
The script doesn't run from Command Prompt or PowerShell, and n8n hasn't verified Git Bash for it, so use WSL on Windows. To write the files yourself, follow the Compose guide, which has you fill in .env, create searxng-settings.yml, get compose.yml from n8n's repository and run docker compose up -d.
# fresh install: creates ./n8n with compose.yml and .env, then starts n8n
curl -fsSL https://get.n8n.io | sh
# stop it, then start it again
docker compose -f ./n8n/compose.yml down
docker compose -f ./n8n/compose.yml up -d
# upgrade, keeping your data, secrets and settings
curl -fsSL https://get.n8n.io | sh -s -- --upgradeWhere your data lives, and how to back it up
n8n keeps everything in one .n8n folder. It holds the config file, which stores the key that encrypts your credentials, and the SQLite database in the default setup. In Docker, that folder is the n8n_data volume mounted at /home/node/.n8n, per the backup guide. A restored database or an encrypted export can't be decrypted without the matching key.
- With SQLite, stop n8n before you copy the folder. Copying the database while n8n writes to it can give you an inconsistent backup.
- To back up only workflows and credentials, run
n8n export:workflow --backup --output=backups/workflows/andn8n export:credentials --backup --output=backups/credentials/, each with its own output folder. - Inside a container, a
backups/folder is not persisted. Copy the files out before you recreate the container. - A CLI backup leaves out users and roles, execution history, variables and instance settings. It moves workflows between instances, and it cannot rebuild one.
- Take a full backup before every update.
Environment variables worth setting first
You pass each variable with -e in a docker run command, as the timezone lines do, or put it in .env for Compose. The proxy page adds that, behind a reverse proxy, the last proxy should set the X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto headers so n8n learns about the original request.
| Variable | What it does | Set it when |
|---|---|---|
GENERIC_TIMEZONE | The timezone for schedule-based nodes such as the Schedule Trigger | Always, so 8 AM means your 8 AM |
TZ | The container's system timezone | Together with the one above |
N8N_WEBHOOK_URL | The public base URL n8n shows in the editor and registers with outside services. It replaces WEBHOOK_URL, deprecated since n8n 2.35.0 | n8n sits behind a reverse proxy |
N8N_PROXY_HOPS | How many reverse proxies stand in front of n8n. The docs set it to 1 in their example | n8n sits behind a reverse proxy |
N8N_ENCRYPTION_KEY | Your own key for encrypting credentials | Before you add the first credential |
N8N_PAYLOAD_SIZE_MAX | The largest request body, in MiB, 16 by default, applied after a restart | Webhooks must take bigger files |
DB_TYPE and DB_POSTGRESDB_* | Switches the database from SQLite to PostgreSQL | A team or a production setup |
Updating without losing work
n8n suggests updating at least once a month, since several small updates carry less risk than one big jump. Read the release notes for breaking changes first, and try the update on a test instance if you have one. Its update guide points to the Docker page for the commands below.
The n8nio/n8n tag is the stable release, and n8nio/n8n:next is the unstable one. For anything you rely on, we'd pin a version number instead of following the tag, so an update happens when you decide. The Compose route already works that way, with N8N_VERSION in .env.
# a container started with docker run
docker pull n8nio/n8n
docker ps -a
docker stop <container_id>
docker rm <container_id>
docker run --name=<container_name> [options] -d n8nio/n8n
# a Docker Compose project
docker compose pull
docker compose down
docker compose up -d- The volume survives the swap. A container started without it starts empty.
- The one-line
--upgradechangesN8N_VERSIONandN8N_SANDBOX_VERSIONin.envand leaves your data, secrets and settings alone.
What n8n's team says about the one-command install and n8n 3.0
On 21 August 2026 the n8n team posted the one-line setup on X. Its pitch is one command with the AI Assistant included, and no Compose file or environment variables to write. For an instance you already run, the post's tip is the same command with --upgrade, the last line of the setup code.
On 28 October 2026 the team announced the next major version in beta. The post promises reliability, stability and security work plus a year of collected breaking changes in one release. Stable lands in early December. The announcement on n8n's blog, by Ophir Prusak, says self-hosted n8n now runs on Docker and that npm and npx n8n installs are no longer supported.
Before you move a running instance to the new version, update it to the latest 2.x and open Settings, then Migration Report, which needs version 2.39 or later. Take a full backup first. The announcement is plain that going back means restoring it.
Already self-hosting? Same command with --upgrade.
Screenshots of X's own embeds of the posts, taken on 5 November 2026, with the time in UTC. Select a screenshot to open the post on X.
Common mistakes
- Running without the volume. Without
-v n8n_data:/home/node/.n8n, your workflows and credentials live and die with the container. - Mistyping a variable. The name is
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS, and n8n's page says outright that it is notN8N_ENFORCE_SETTINGS_PERMISSIONS. - Using
-vwithdocker compose downto restart. That flag deletes all n8n data, and n8n lists it only under uninstall. - Switching to Postgres and expecting your workflows to follow. Existing SQLite data does not carry over. Keep
n8n_datamounted too, because the folder still holds encryption keys, logs and source control assets. - Publishing more than n8n's own port. The Compose stack's sandbox runner is privileged, and n8n calls it effectively root on the host.
- Running the one-line script from PowerShell, or keeping a Compose project under
/mnt/con WSL. Use WSL, and keep the project inside its own filesystem.
Try it yourself
- Start n8n with your timezone, rebuild the schedule from lesson 1 and check that 8 AM lands at 8 AM for you.
- Stop and recreate the container, then confirm your workflows are still there.
- Run the export command from the backup guide inside the container, then copy the results to the host.
- Rebuild the webhook from lesson 2 and compare the URL the editor shows with the address you open in your browser.
- Open the
compose.ymlthe one-line script wrote and find the volume and the port.
What to learn next
You now have a running n8n, a first workflow, a webhook and an agent. The next course, n8n advanced, starts with error workflows. The Error Trigger, retries and Stop And Error keep a workflow that runs on its own from failing without anyone noticing. The same course then covers sub-workflows, the Code node and queue mode for scaling. For something to run on your new server, import an n8n workflow from Mindket's n8n workflows and open it in your own editor.
Check yourself
You run n8n with docker run and later recreate the container. Where must your data live to survive?
Show answer
B. In a volume mounted at /home/node/.n8n The --rm flag removes the container when it stops, so workflows and credentials must sit on the volume mounted at /home/node/.n8n.
Which variable do you set so that schedule-based nodes fire at your own 8 AM?
Show answer
D. GENERIC_TIMEZONE GENERIC_TIMEZONE sets the timezone for nodes such as the Schedule Trigger, and the docs set TZ with it for the container itself.
Why should you copy the config file, or set your own N8N_ENCRYPTION_KEY, on the day you install?
Show answer
A. A restored database or export cannot be decrypted without the matching key The config file holds the key that encrypts your credentials, and after a disk failure there is nothing left to save.
Which command deletes all your n8n data when you only meant to restart a Compose project?
Show answer
C. docker compose down -v The -v flag removes the volumes, and n8n lists it only under uninstall.
Frequently asked questions
Which Docker image does n8n use?
n8nio/n8n. The README spells it docker.n8n.io/n8nio/n8n, and the Compose file pulls docker.io/n8nio/n8n with the version from .env. A next tag exists for unstable builds, and the README shows both quick starts.
How do I check that n8n is running?
In the Compose setup, run docker compose ps and wait until sandbox-api shows healthy. Then call curl -sf http://localhost:5678/healthz or open http://localhost:5678 in a browser, as the Compose guide does.
Does self-hosted n8n need a separate database?
No. It ships with SQLite, which is enough to start. n8n suggests Postgres for teams and production, and moving to it later means your old SQLite data stays behind.
What are the extra containers in the one-line setup?
Besides n8n, the stack starts a code sandbox, a runner for Code node tasks and a search tool. They support n8n Assistant, which stays off until you add an AI provider key. The sandbox runner is privileged, so never publish its ports.
Can I use Podman or Colima instead of Docker?
Yes, for Docker-compatible engines. The one-line setup page says to install the docker CLI with the compose plugin and set DOCKER_HOST to the engine's socket.
Is self-hosted n8n free?
The Community edition is free with almost the complete feature set. Registering it, also free, adds folders, debug in editor and custom execution data. Business and Enterprise are paid, per n8n's comparison page.
Where does n8n keep its files outside Docker?
In ~/.n8n by default. If you set N8N_USER_FOLDER, n8n uses the .n8n subfolder of that path instead. Existing npm installs keep working, and the folder holds the same config file and SQLite database that the Docker volume does.
Sources
- n8n Docs: Install options https://docs.n8n.io/deploy/host-n8n/install-options
- n8n Docs: Install with Docker https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker
- n8n Docs: Install using Docker Compose https://docs.n8n.io/deploy/host-n8n/install-options/install-using-docker-compose
- n8n Docs: One-line setup https://docs.n8n.io/deploy/host-n8n/install-options/one-line-setup
- n8n Docs: Update n8n https://docs.n8n.io/deploy/host-n8n/keep-n8n-running/update-n8n
- n8n Docs: Back up and restore https://docs.n8n.io/deploy/host-n8n/keep-n8n-running/backup-and-restore
- n8n Docs: Endpoints environment variables https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/use-environment-variables/endpoints
- n8n Docs: Configure webhook URLs with a reverse proxy https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/configuration-examples/configure-webhook-urls-with-reverse-proxy
- n8n Docs: Choose how to use n8n https://docs.n8n.io/choose-how-to-use-n8n
- GitHub: n8n-io/n8n https://github.com/n8n-io/n8n
- GitHub: n8n-io/n8n get-n8n-compose.yml https://raw.githubusercontent.com/n8n-io/n8n/master/docker/get-n8n-compose.yml
- n8n Docs: Release notes https://docs.n8n.io/changelog/release-notes
- n8n Blog: Introducing n8n 3.0 https://blog.n8n.io/introducing-n8n-v3/
- n8n.io on X: one command to self-host n8n, 21 August 2026 https://x.com/n8n_io/status/2090756675472949712
- n8n.io on X: n8n 3.0 is now in beta, 28 October 2026 https://x.com/n8n_io/status/2115459582042534340