Development Setup

Set up your local n8n development environment with pnpm, Node.js, and all required dependencies

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:

Debian/Ubuntu

apt-get install -y build-essential python

yum install gcc gcc-c++ make

npm add -g windows-build-tools

# No additional packages required
# Xcode Command Line Tools are sufficient

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:

Backend-only development

pnpm dev:be

Excludes frontend packages like editor-ui and design-system.

Frontend-only development

pnpm dev:fe

Runs editor-ui and design-system development servers.

AI/LangChain nodes development

pnpm dev:ai

Runs only essential packages for AI node development.

Most Common Development Workflow

Many n8n developers use this two-terminal setup:

Terminal 1: Backend (CLI)

cd packages/cli
pnpm dev

cd packages/frontend/editor-ui
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:

Terminal 1: Watch nodes package

cd packages/nodes-base
pnpm dev

cd packages/cli
N8N_DEV_RELOAD=true 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

   SQLite

   pnpm --filter n8n-containers stack:sqlite
   

   pnpm --filter n8n-containers stack:postgres
   

   pnpm --filter n8n-containers stack:queue
   

   pnpm --filter n8n-containers stack:multi-main
   
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

Build fails with dependency errors

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+
   

Port 5678 is already in use

Change the port with an environment variable:

N8N_PORT=5679 pnpm start

Hot reload not working

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

Docker alternatives (Podman, Colima)

Testcontainers requires additional configuration for Docker alternatives:

• Podman: Follow this guide
• Colima: Set environment variables as described here

Next Steps

• Learn about n8n’s architecture
• Understand the testing practices
• Review contribution guidelines before submitting PRs