Local Setup

Install dependencies and configure your Grafana development environment

This guide walks you through setting up a local development environment for Grafana.

Prerequisites

Ensure you have the following installed:

Required Dependencies

• Git: For cloning the repository
• Go: See go.mod for the minimum required version (currently 1.25.8)
• Node.js (LTS): Version 24.x with corepack enabled (see .nvmrc)
  • We recommend using a version manager like nvm or fnm
• GCC (optional): Enables CGO for smaller, dynamically-linked binaries with SQLite support

Platform-Specific Instructions

macOS

Install dependencies using Homebrew:

brew install git
brew install go
brew install node@24

Windows

We recommend using Windows Subsystem for Linux (WSL) for development on Windows.

Follow the Grafana setup guide for Windows.

If building natively on Windows:

• Install GCC with binutils 2.37+ (e.g., MinGW x64)
• Install Make for Windows to use Makefile commands

Linux

Use your distribution’s package manager to install Git, Go, and Node.js.

Example for Ubuntu/Debian:

sudo apt update
sudo apt install git golang nodejs

Clone the Repository

1. Clone the repository

   git clone https://github.com/grafana/grafana.git
   cd grafana
   

   Do NOT use go get to download Grafana. Recent versions of Go have behavior that isn’t compatible with how the Grafana repository is structured.

2. Enable and install Yarn via corepack

   Grafana uses Yarn 4.11.0 for frontend dependency management:

   corepack enable
   corepack install
   
3. Install frontend dependencies

   yarn install --immutable
   

   Troubleshooting: Checksum mismatch errors

   If you get an error about remote archive checksum mismatch:

   YARN_CHECKSUM_BEHAVIOR=update yarn install --immutable
   

Configure Pre-commit Hooks (Optional)

Pre-commit hooks lint, fix, and format code as you commit. They’re opt-in for contributors.

Install hooks

make lefthook-install

We strongly encourage frontend contributors to install pre-commit hooks to keep eslint-suppressions.json in sync, even if your IDE formats on save.

Configure Development Environment

Create Custom Configuration

The default configuration is in conf/defaults.ini. To override settings:

1. Create custom.ini

   touch conf/custom.ini
   
2. Enable development mode

   Add this to conf/custom.ini:

   app_mode = development
   
3. Add any other overrides (optional)

   You only need to add settings you want to override from defaults.ini.

Set Up Data Sources (Optional)

To test with real data sources during development:

1. Install Docker

   Grafana uses Docker to run databases in the background.

   Install Docker before proceeding.

2. Start data source containers

   From the repository root:

   make devenv sources=influxdb,loki
   

   This generates a Docker Compose file with your specified data sources and runs them.

   Available data sources

   See the devenv/docker/blocks directory for all available sources.

   Some have macOS-specific images (e.g., nginx_proxy_mac).

3. Set up dashboards and data sources

   cd devenv
   ./setup.sh
   

   This creates:

   • Data sources named gdev-<type>
   • Dashboards in the “gdev dashboards” folder
4. Stop data sources when done

   make devenv-down
   

Troubleshooting

Too Many Open Files (macOS/Linux)

If you encounter “too many open files” errors:

1. Check current limit

   ulimit -a
   
2. Increase the limit

   ulimit -S -n 8000
   

   To determine the number needed:

   find ./conf ./pkg ./public/views | wc -l
   
3. Make it permanent

   Add to your shell initialization file (~/.zshrc or ~/.bashrc):

   echo "ulimit -S -n 8000" >> ~/.zshrc
   

File Watchers Limit (Linux)

If you see “System limit for number of file watchers reached”:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Verify:

cat /proc/sys/fs/inotify/max_user_watches

File Watchers Limit (macOS)

sudo sysctl -w kern.maxfiles=524288

Verify:

sysctl kern.maxfiles

JavaScript Heap Out of Memory

If Node.js runs out of memory:

export NODE_OPTIONS="--max-old-space-size=8192"

On Windows:

Set NODE_OPTIONS="--max-old-space-size=8192"

IDE Configuration

Configure your IDE to use the TypeScript version from node_modules/.bin/tsc (should match package.json).

Grafana previously used Yarn PnP, but now uses standard node_modules. If you have custom ESLint, Prettier, or TypeScript paths configured, you can remove them.

Next Steps

Project Structure

Learn how the monorepo is organized

Building

Build and run Grafana locally