Skip to main content
This guide will help you set up your local environment to contribute code to the Gutenberg project.

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Node.js

Gutenberg requires Node.js. The project currently uses Node.js v20 and npm v10. While we aim to use the Active LTS version, this may vary. We recommend using Node Version Manager (nvm) to manage Node.js versions: 
# Install the version specified in .nvmrc
nvm install
nvm use

​
Git

Gutenberg uses Git for source control. Ensure you have:
  • An updated version of Git installed
  • A GitHub account
See the Development Workflow guide for details on using Git with Gutenberg. We recommend using the @wordpress/env package for your local WordPress environment. Docker is required for this: Alternatives: You can also use Local, WampServer, MAMP, or a remote server.

​
GitHub CLI (Optional)

The GitHub CLI can be very useful for checking out pull requests locally from both the main repository and forks.

​
Getting the Gutenberg Code

​
Fork and Clone

Fork the Gutenberg repository to your GitHub account, then clone it: 
git clone https://github.com/YOUR_GITHUB_USERNAME/gutenberg.git
cd gutenberg
git remote add upstream https://github.com/WordPress/gutenberg.git

​
Building Gutenberg

​
Install Dependencies

Install the project dependencies: 
npm install
Note: This requires Python to be installed and in your system path.

​
Build the Plugin

You have two build options: For active development with automatic rebuilds: 
npm run dev
This runs continuous builds as source files change and includes additional warnings and errors for troubleshooting.

​
Production Build

For optimized production builds: 
npm run build

​
Local WordPress Environment

The @wordpress/env package provides a quick way to create a standard WordPress environment using Docker.

​
Start the Environment

Make sure Docker is running, then start wp-env from the Gutenberg directory: 
npm run wp-env start
This creates a Docker instance with:
  • Latest WordPress Docker image
  • Gutenberg plugin mounted and activated
  • Live reload of your local code changes

​
Access WordPress

​
Database Access

phpMyAdmin: Available at http://localhost:9000/ Direct MySQL Connection:
  1. Run npm run wp-env start and note the MySQL port number
  2. Use these connection details:
    • Host: 127.0.0.1
    • Username: root
    • Password: password
    • Database: wordpress
    • Port: (from step 1)
Note: The MySQL port changes each time wp-env restarts.

​
wp-env Commands

# Stop the environment
npm run wp-env stop

# Destroy the environment completely
npm run wp-env destroy

# Check environment status
npm run wp-env status

​
Using Local or MAMP

If you prefer Local, MAMP, or WampServer:
  1. Clone and build Gutenberg as described above
  2. Create a symlink or copy the Gutenberg directory to your wp-content/plugins folder
  3. For e2e tests, symlink test plugins:
cd wp-content/plugins
ln -s gutenberg/packages/e2e-tests/plugins/* .

​
Developer Tools

Configure your editor for the best development experience:

​
EditorConfig

Install the EditorConfig extension for your editor. It will automatically configure your editor to match the project’s coding standards.

​
ESLint

Install the ESLint extension for your editor: Configure auto-fix on save in VS Code: 
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

​
Prettier

Install the Prettier extension: Configure formatting on save in VS Code: 
{
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

​
TypeScript

The project uses TypeScript via JSDoc for type checking JavaScript files. VS Code has built-in TypeScript support.

​
Storybook

Test and develop UI components in isolation with Storybook: 
npm run storybook:dev
View the live Storybook: https://wordpress.github.io/gutenberg/

​
Next Steps

Now that your environment is set up:

Build docs developers (and LLMs) love

Get started for freeTalk to us