Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

​
Node.js

Node.js version 24 or newer is required for development. 
node --version  # Should be 24.x or higher

​
pnpm Package Manager

n8n uses pnpm version 10.22 or newer as its package manager. We recommend installing it with corepack for automatic version management.
pnpm workspaces automatically manage file-links between modules that depend on each other in the monorepo.

​
Corepack

Enable Node.js corepack to manage pnpm automatically: 
corepack enable
corepack prepare pnpm@10.22.0 --activate
macOS (Homebrew users): If you installed Node.js via Homebrew, you need to install corepack separately:
brew install corepack
Homebrew explicitly removes npm and corepack from the Node.js formula.
Windows users: Run the corepack commands in a terminal with administrator privileges:
corepack enable
corepack prepare pnpm@10.22.0 --activate

​
Build Tools

Some n8n dependencies require native compilation. Install the appropriate build tools for your operating system: 
apt-get install -y build-essential python

​
actionlint (Optional)

If you plan to modify GitHub Actions workflow files, install actionlint: 
# macOS
brew install actionlint
actionlint is only required when modifying .github/workflows/*.yml files. It runs automatically via git hooks when workflow files change.

​
Development Container (Optional)

If you use VS Code with Docker, you can use n8n’s Dev Container for a pre-configured environment:
  1. Install VS Code and Docker
  2. Click here to automatically clone and open n8n in a Dev Container
The Dev Container includes all required tools and dependencies.

​
Initial Setup

​
For External Contributors

1

Fork the repository

Go to n8n-io/n8n and click the “Fork” button in the top-right corner.
2

Clone your fork

git clone https://github.com/<your_github_username>/n8n.git
cd n8n
3

Add upstream remote

git remote add upstream https://github.com/n8n-io/n8n.git
This allows you to sync with the original repository:
git fetch upstream
git merge upstream/master
4

Install dependencies

pnpm install
This installs all dependencies for all packages and automatically links them together using pnpm workspaces.
5

Build all packages

pnpm build
Performance tip: Redirect build output to a file to avoid overwhelming your terminal:
pnpm build > build.log 2>&1
tail -n 20 build.log  # Check for errors

​
For n8n Team Members

1

Clone the repository

git clone https://github.com/n8n-io/n8n.git
cd n8n
2

Install dependencies

pnpm install
3

Build all packages

pnpm build > build.log 2>&1

​
Starting n8n

After the initial setup, start n8n in production mode: 
pnpm start
n8n will be available at http://localhost:5678

​
Development Mode

For active development with hot-reload, use development mode:

​
Full Stack Development

pnpm dev
This starts all packages in watch mode with automatic rebuilding and hot-reload.
Performance impact: Full development mode runs multiple processes in parallel:
  • TypeScript compilation for each package
  • File watchers monitoring source files
  • Nodemon restarting the backend
  • Vite dev server with HMR for frontend
  • Build processes for various packages
This can consume significant CPU and memory. See Selective Development for optimized workflows.

​
Selective Development

Run only the packages you’re actively working on for better performance: 
pnpm dev:be
Excludes frontend packages like editor-ui and design-system.
pnpm dev:fe
Runs editor-ui and design-system development servers.
pnpm dev:ai
Runs only essential packages for AI node development.

​
Most Common Development Workflow

Many n8n developers use this two-terminal setup: 
cd packages/cli
pnpm dev
If you modify code outside packages/cli or packages/frontend/editor-ui, run pnpm build to rebuild those packages.

​
Custom Node Development

For developing custom nodes with hot-reload: 
cd packages/nodes-base
pnpm dev
Performance considerations:The N8N_DEV_RELOAD feature watches potentially thousands of files. On resource-constrained systems, consider developing without hot reload and manually restarting when needed.

​
Testing with Different Configurations

n8n uses Testcontainers to quickly spin up local instances with different configurations:
1

Build a Docker image

Build from your branch:
pnpm build:docker
Or use an existing image:
export N8N_DOCKER_IMAGE=n8nio/n8n:latest
2

Run a stack

pnpm --filter n8n-containers stack:sqlite
3

Customize or scale (optional)

Customize with environment variables:
pnpm --filter n8n-containers stack --env N8N_ENABLED_MODULES=insights
Scale up workers:
pnpm --filter n8n-containers stack --queue --mains 4 --workers 20
Each instance gets its own port. Multi-main stacks use a load balancer by default. See packages/testing/containers/README.md for more details.

​
Testing with Clean Database

To test features with a fresh n8n instance without losing your existing setup, use a different user folder: 
N8N_USER_FOLDER=~/.n8n-test pnpm --filter n8n start
Each folder maintains its own database, settings, and workflows.

​
Troubleshooting

  1. Clear node_modules and reinstall: 
    pnpm reset
pnpm install
pnpm build
  2. Ensure you’re using the correct Node.js and pnpm versions: 
    node --version  # Should be 24.x+
pnpm --version  # Should be 10.22.0+
Change the port with an environment variable:
N8N_PORT=5679 pnpm start
Ensure you’re using N8N_DEV_RELOAD=true and that the relevant packages are running in watch mode:
cd packages/nodes-base && pnpm dev  # Terminal 1
cd packages/cli && N8N_DEV_RELOAD=true pnpm dev  # Terminal 2
Testcontainers requires additional configuration for Docker alternatives:
  • Podman: Follow this guide
  • Colima: Set environment variables as described here

​
Next Steps