Installation on Grafana Labs

Configure Grafana Docker image

Wed, 15 Apr 2026 19:44:45 +0000

Configure a Grafana Docker image

If you are running Grafana in a Docker image, then you configure Grafana using environment variables rather than directly editing the configuration file. If you want to save your data, then you also need to designate persistent storage or bind mounts for the Grafana container.

Save your Grafana data

If you do not designate a location for information storage, then all your Grafana data disappears as soon as you stop your image. To save your data, you need to set up persistent storage or bind mounts for your container.

Run Grafana container with persistent storage (recommended)

# create a persistent volume for your data in /var/lib/grafana (database and plugins)
docker volume create grafana-storage

# start grafana
docker run -d -p 3000:3000 --name=grafana -v grafana-storage:/var/lib/grafana grafana/grafana

Run Grafana container using bind mounts

You may want to run Grafana in Docker but use folders on your host for the database or configuration. When doing so, it becomes important to start the container with a user that is able to access and write to the folder you map into the container.

mkdir data # creates a folder for your data
ID=$(id -u) # saves your user id in the ID variable

# starts grafana with your user id and using the data folder
docker run -d --user $ID --volume "$PWD/data:/var/lib/grafana" -p 3000:3000 grafana/grafana:5.1.0

Default paths

The following settings are hard-coded when launching the Grafana Docker container and can only be overridden using environment variables, not in conf/grafana.ini.

Setting	Default value
GF_PATHS_CONFIG	/etc/grafana/grafana.ini
GF_PATHS_DATA	/var/lib/grafana
GF_PATHS_HOME	/usr/share/grafana
GF_PATHS_LOGS	/var/log/grafana
GF_PATHS_PLUGINS	/var/lib/grafana/plugins
GF_PATHS_PROVISIONING	/etc/grafana/provisioning

Configure Grafana with Docker Secrets

Only available in Grafana v5.2 and later.

It’s possible to supply Grafana with configuration through files. This works well with Docker Secrets as the secrets by default gets mapped into /run/secrets/<name of secret> of the container.

You can do this with any of the configuration options in conf/grafana.ini by setting GF_<SectionName>_<KeyName>__FILE to the path of the file holding the secret.

For example, you could set the admin password this way:

Admin password secret: /run/secrets/admin_password
Environment variable: GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password

Configure AWS credentials for CloudWatch Support

docker run -d \
-p 3000:3000 \
--name=grafana \
-e "GF_AWS_PROFILES=default" \
-e "GF_AWS_default_ACCESS_KEY_ID=YOUR_ACCESS_KEY" \
-e "GF_AWS_default_SECRET_ACCESS_KEY=YOUR_SECRET_KEY" \
-e "GF_AWS_default_REGION=us-east-1" \
grafana/grafana

You may also specify multiple profiles to GF_AWS_PROFILES (e.g. GF_AWS_PROFILES=default another).

Supported variables:

GF_AWS_${profile}_ACCESS_KEY_ID: AWS access key ID (required).
GF_AWS_${profile}_SECRET_ACCESS_KEY: AWS secret access key (required).
GF_AWS_${profile}_REGION: AWS region (optional).

Install on Debian/Ubuntu

Wed, 15 Apr 2026 19:44:45 +0000

Install on Debian or Ubuntu

This page explains how to install Grafana dependencies, download and install Grafana, get the service up and running on your Debian or Ubuntu system, and also describes the installation package details.

Note on upgrading: While the process for upgrading Grafana is very similar to installing Grafana, there are some key backup steps you should perform. Read Upgrading Grafana for tips and guidance on updating an existing installation.

1. Download and install

You can install Grafana using our official APT repository, by downloading a .deb package, or by downloading a binary .tar.gz file.

Install from APT repository

If you install from the APT repository, then Grafana is automatically updated every time you run apt-get update.

Grafana Version	Package	Repository
Grafana OSS	grafana	`https://packages.grafana.com/oss/deb stable main`
Grafana OSS (Beta)	grafana	`https://packages.grafana.com/oss/deb beta main`
Grafana Enterprise	grafana-enterprise	`https://packages.grafana.com/enterprise/deb stable main`
Grafana Enterprise (Beta)	grafana-enterprise	`https://packages.grafana.com/enterprise/deb beta main`

We recommend all users install the Enterprise Edition of Grafana, which can be seamlessly upgraded with a Grafana Enterprise subscription.

To install the latest Enterprise edition:

sudo apt-get install -y apt-transport-https
sudo apt-get install -y software-properties-common wget
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -

Add this repository for stable releases:

```bash
echo "deb https://packages.grafana.com/enterprise/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list

Add this repository if you want beta releases:

echo "deb https://packages.grafana.com/enterprise/deb beta main" | sudo tee -a /etc/apt/sources.list.d/grafana.list

After you add the repository:

sudo apt-get update
sudo apt-get install grafana-enterprise

To install the latest OSS release:

sudo apt-get install -y apt-transport-https
sudo apt-get install -y software-properties-common wget
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -

Add this repository for stable releases:

echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list

Add this repository if you want beta releases:

echo "deb https://packages.grafana.com/oss/deb beta main" | sudo tee -a /etc/apt/sources.list.d/grafana.list

After you add the repository:

sudo apt-get update
sudo apt-get install grafana

Install .deb package

If you install the .deb package, then you will need to manually update Grafana for each new version.

On the Grafana download page, select the Grafana version you want to install.
- The most recent Grafana version is selected by default.
- The Version field displays only finished releases. If you want to install a beta version, click Nightly Builds and then select a version.
Select an Edition.
- Enterprise - Recommended download. Functionally identical to the open source version, but includes features you can unlock with a license if you so choose.
- Open Source - Functionally identical to the Enterprise version, but you will need to download the Enterprise version if you want Enterprise features.
Depending on which system you are running, click Linux or ARM.
Copy and paste the code from the installation page into your command line and run. It follows the pattern shown below.

sudo apt-get install -y adduser libfontconfig1
wget <.deb package url>
sudo dpkg -i grafana<edition>_<version>_amd64.deb

Install from binary .tar.gz file

Download the latest .tar.gz file and extract it. The files extract into a folder named after the Grafana version downloaded. This folder contains all files required to run Grafana. There are no init scripts or install scripts in this package.

wget <tar.gz package url>
sudo tar -zxvf <tar.gz package>

2. Start the server

This starts the grafana-server process as the grafana user, which was created during the package installation.

If you installed with the APT repository or .deb package, then you can start the server using systemd or init.d. If you installed a binary .tar.gz file, then you need to execute the binary.

Start the server with systemd

To start the service and verify that the service has started:

sudo systemctl daemon-reload
sudo systemctl start grafana-server
sudo systemctl status grafana-server

Configure the Grafana server to start at boot:

sudo systemctl enable grafana-server.service

Start the server with init.d

To start the service and verify that the service has started:

sudo service grafana-server start
sudo service grafana-server status

Configure the Grafana server to start at boot:

sudo update-rc.d grafana-server defaults

Execute the binary

The grafana-server binary .tar.gz needs the working directory to be the root install directory where the binary and the public folder are located.

Start Grafana by running:

./bin/grafana-server web

Package details

Installs binary to /usr/sbin/grafana-server
Installs Init.d script to /etc/init.d/grafana-server
Creates default file (environment vars) to /etc/default/grafana-server
Installs configuration file to /etc/grafana/grafana.ini
Installs systemd service (if systemd is available) name grafana-server.service
The default configuration sets the log file at /var/log/grafana/grafana.log
The default configuration specifies an sqlite3 db at /var/lib/grafana/grafana.db
Installs HTML/JS/CSS and other Grafana files at /usr/share/grafana

Next steps

Refer to the Getting Started guide for information about logging in, setting up data sources, and so on.

Configure Grafana

Refer to the Configuration page for details on options for customizing your environment, logging, database, and so on.

Install on macOS

Wed, 15 Apr 2026 19:44:45 +0000

Install on macOS

This page provides instructions to help you install Grafana on macOS.

1. Download and install

Before you begin, you must have Homebrew installed.

On the Grafana download page, select the Grafana version you want to install.
- The most recent Grafana version is selected by default.
- The Version field displays only finished releases. If you want to install a beta version, click Nightly Builds and then select a version.
Select an Edition.
- Open Source - Functionally identical to the enterprise version, but you will need to download the enterprise version if you want enterprise features.
- Enterprise - Not currently available for Mac.
Click Mac.
Copy and paste the code from the installation page into your command line and run. It follows the pattern shown below.
Bash
```
brew update
brew install grafana
```

2. Start Grafana

Start Grafana using Homebrew services:

brew services start grafana

Upgrade with Homebrew

To upgrade Grafana, use the reinstall command:

brew update
brew reinstall grafana

Install on RPM-based Linux

Wed, 15 Apr 2026 19:44:45 +0000

Install on RPM-based Linux (CentOS, Fedora, OpenSuse, Red Hat)

This page explains how to install Grafana dependencies, download and install Grafana, get the service up and running on your RPM-based Linux system, and the installation package details.

1. Download and install

You can install Grafana from a YUM repository, manually using YUM, manually using RPM, or by downloading a binary .tar.gz file.

Install from YUM repository

If you install from the YUM repository, then Grafana is automatically updated every time you run sudo yum update.

Grafana Version	Package	Repository
Grafana OSS	grafana	`https://packages.grafana.com/oss/rpm`
Grafana OSS (Beta)	grafana	`https://packages.grafana.com/oss/rpm-beta`
Grafana Enterprise	grafana-enterprise	`https://packages.grafana.com/enterprise/rpm`
Grafana Enterprise (Beta)	grafana-enterprise	`https://packages.grafana.com/enterprise/rpm-beta`

Add a new file to your YUM repo using the method of your choice. The command below uses nano.

sudo nano /etc/yum.repos.d/grafana.repo

Choose if you want to install the Open Source or Enterprise edition of Grafana and enter the information from the edition you’ve chosen into grafana.repo. If you want to install the beta version of Grafana you need to replace the URL with a beta URL from the table above.

We recommend all users to install the Enterprise Edition of Grafana, which can be seamlessly upgraded with a Grafana Enterprise subscription.

For Enterprise releases:

[grafana]
name=grafana
baseurl=https://packages.grafana.com/enterprise/rpm
repo_gpgcheck=1
enabled=1
gpgcheck=1
gpgkey=https://packages.grafana.com/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt

For OSS releases:

[grafana]
name=grafana
baseurl=https://packages.grafana.com/oss/rpm
repo_gpgcheck=1
enabled=1
gpgcheck=1
gpgkey=https://packages.grafana.com/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt

Install Grafana with one of the following commands:

sudo yum install grafana

# or

sudo yum install grafana-enterprise

Install manually with YUM

If you install manually with YUM, then you will need to manually update Grafana for each new version. To enable automatic updates for your Grafana installation please use the instructions below to install via our YUM repository.

On the Grafana download page, select the Grafana version you want to install.
- The most recent Grafana version is selected by default.
- The Version field displays only finished releases. If you want to install a beta version, click Nightly Builds and then select a version.
Select an Edition.
- Enterprise - Recommended download. Functionally identical to the open source version, but includes features you can unlock with a license if you so choose.
- Open Source - Functionally identical to the Enterprise version, but you will need to download the Enterprise version if you want enterprise features.
Depending on which system you are running, click Linux or ARM.
Copy and paste the code from the installation page into your command line and run. It follows the pattern shown below.

wget <rpm package url>
sudo yum localinstall <local rpm package>

You can also install Grafana using YUM directly:

sudo yum install <rpm package url>

Install with RPM

If you install with RPM, then you will need to manually update Grafana for each new version. This method varies according to which Linux OS you are running. Read the instructions fully before you begin.

Note: The .rpm files are signed, you can verify the signature with this public GPG key.

On the Grafana download page, select the Grafana version you want to install.
- The most recent Grafana version is selected by default.
- The Version field displays only finished releases. If you want to install a beta version, click Nightly Builds and then select a version.
Select an Edition.
- Enterprise - Recommended download. Functionally identical to the open source version, but includes features you can unlock with a license if you so choose.
- Open Source - Functionally identical to the Enterprise version, but you will need to download the Enterprise version if you want Enterprise features.
Depending on which system you are running, click Linux or ARM.
Copy and paste the .rpm package URL and the local .rpm package information from the installation page into the pattern shown below, then run the commands.

On CentOS, Fedora, Red Hat, or RHEL:

sudo yum install initscripts urw-fonts wget
wget <rpm package url>
sudo rpm -Uvh <local rpm package>

On OpenSUSE or SUSE:

wget <rpm package url>
sudo rpm -i --nodeps <local rpm package>

Install from binary .tar.gz file

Download the latest .tar.gz file and extract it. The files are extracted into a folder named after the Grafana version that you downloaded. This folder contains all files required to run Grafana. There are no init scripts or install scripts in this package.

wget <tar.gz package url>
sudo tar -zxvf <tar.gz package>

2. Start the server

This starts the grafana-server process as the grafana user, which was created during the package installation. The systemd commands work in most cases, but some older Linux systems might require init.d. The installer should prompt you with the correct commands.

If you installed with an .rpm package, then you can start the server using systemd or init.d. If you installed a binary .tar.gz file, then you need to execute the binary.

Start the server with systemd

To start the service and verify that the service has started:

sudo systemctl daemon-reload
sudo systemctl start grafana-server
sudo systemctl status grafana-server

Configure the Grafana server to start at boot:

sudo systemctl enable grafana-server

SUSE or OpenSUSE users: You might need to start the server with the systemd method, then use the init.d method to configure Grafana to start at boot.

Start the server with init.d

To start the service and verify that the service has started:

sudo service grafana-server start
sudo service grafana-server status

Configure the Grafana server to start at boot:

sudo /sbin/chkconfig --add grafana-server

Execute the binary

The grafana-server binary needs the working directory to be the root install directory where the binary and the public folder are located.

Start Grafana by running:

./bin/grafana-server web

Package details

Installs binary to /usr/sbin/grafana-server
Copies init.d script to /etc/init.d/grafana-server
Installs default file (environment vars) to /etc/sysconfig/grafana-server
Copies configuration file to /etc/grafana/grafana.ini
Installs systemd service (if systemd is available) name grafana-server.service
The default configuration uses a log file at /var/log/grafana/grafana.log
The default configuration specifies an sqlite3 database at /var/lib/grafana/grafana.db

Next steps

Refer to the Getting Started guide for information about logging in, setting up data sources, and so on.

Configure Grafana

Refer to the Configuration page for details on options for customizing your environment, logging, database, and so on.

Install on Windows

Wed, 15 Apr 2026 19:44:45 +0000

Install on Windows

You can either download the Windows installer package or a standalone Windows binary file.

Read Upgrading Grafana for tips and guidance on updating an existing installation.

Navigate to Download Grafana.
Select a Grafana version you want to install.
- The most recent Grafana version is selected by default.
- The Version field displays only finished releases. If you want to install a beta version, click Nightly Builds and then select a version.
Select an Edition.
- Enterprise - Recommended download. Functionally identical to the open source version, but includes features you can unlock with a license if you so choose.
- Open Source - Functionally identical to the enterprise version, but you will need to download the enterprise version if you want enterprise features.
Click Windows.

You can either use the Windows installer or you can install a standalone Windows binary.

Install with Windows installer (recommended)

Click Download the installer.
Open and run the installer.

To run Grafana, open your browser and go to the Grafana port (http://localhost:3000/ is default) and then follow the instructions in Getting Started.

Install standalone Windows binary

Click Download the zip file. Important: After you’ve downloaded the zip file and before extracting it, make sure to open the properties for that file (right-click Properties) and select the unblock check box and then click Ok.
Extract this folder to anywhere you want Grafana to run from.
Start Grafana by executing grafana-server.exe, located in the bin directory, preferably from the command line. If you want to run Grafana as a Windows service, then download NSSM. It is very easy to add Grafana as a Windows service using that tool.

To run Grafana, open your browser and go to the Grafana port (http://localhost:3000/ is default) and then follow the instructions in Getting Started.

Note: The default Grafana port is 3000. This port might require extra permissions on Windows. If it does not appear in the default port, you can try changing to a different port.

Go into the conf directory and copy sample.ini to custom.ini. Note: You should edit custom.ini, never defaults.ini.

Edit custom.ini and uncomment the http_port configuration option (; is the comment character in ini files) and change it to something like 8080 or similar. That port should not require extra Windows privileges. Read more about the configuration options.

Migrating from older versions

Wed, 15 Apr 2026 19:44:45 +0000

Migrating from older versions

Normally new versions of Grafana are backward compatible. Any changes to database or dashboard schema will be automatically migrated when Grafana-server start up without any user action required.

Migrating from v1.x to v2.x

Grafana 2.0 represents a major update to Grafana. It brings new capabilities, many of which are enabled by its new back-end server and integrated database.

The new back-end lays a solid foundation that we hope to build on over the coming months. For the 2.0 release, it enables authentication as well as server-side sharing and rendering.

We’ve attempted to provide a smooth migration path for v1.9 users to migrate to Grafana 2.0.

Adding Data sources

The config.js file has been deprecated. Data sources are now managed via the UI or HTTP API. Manage your organizations data sources by clicking on the Data Sources menu on the side menu (which can be toggled via the Grafana icon in the upper left of your browser).

From here, you can add any Graphite, InfluxDB, elasticsearch, and OpenTSDB data sources that you were using with Grafana 1.x. Grafana 2.0 can be configured to communicate with your data source using a back-end mode which can eliminate many CORS-related issues, as well as provide more secure authentication to your data sources.

Note When you add your data sources please name them exactly as you named them in config.js in Grafana 1.x. That name is referenced by panels, annotation and template queries. That way when you import your old dashboard they will work without any changes.

Importing your existing dashboards

Grafana 2.0 now has integrated dashboard storage engine that can be configured to use an internal sqlite3 database, MySQL, or Postgres. This eliminates the need to use Elasticsearch for dashboard storage for Graphite users. Grafana 2.0 does not support storing dashboards in InfluxDB.

You can seamlessly import your existing dashboards.

Importing dashboards from Elasticsearch

Start by going to the Data Sources view (via the side menu), and make sure your Elasticsearch data source is added. Specify the Elasticsearch index name where your existing Grafana v1.x dashboards are stored (the default is grafana-dash).

Importing dashboards from InfluxDB

Start by going to the Data Sources view (via the side menu), and make sure your InfluxDB data source is added. Specify the database name where your Grafana v1.x dashboards are stored, the default is grafana.

Go to Import dashboards view

Go to the Dashboards view and click on the dashboards search drop down. Click the Import button at the bottom of the search drop down.

Import view

In the Import view you find the section Migrate dashboards. Pick the data source you added (from Elasticsearch or InfluxDB), and click the Import button.

Your dashboards should be automatically imported into the Grafana 2.0 back-end.

Dashboards will no longer be stored in your previous Elasticsearch or InfluxDB databases.

Invite your team

Explain users and orgs.

Enjoy the new features

Requirements

Wed, 15 Apr 2026 19:44:45 +0000

Grafana requirements

This page lists the minimum hardware and software requirements to install Grafana.

To run Grafana, you must have a supported operating system, hardware that meets or exceeds minimum requirements, a supported database, and a supported browser

Supported operating systems

The following operating systems are supported for Grafana installation:

While you can install Grafana on other operating systems, we do not recommend doing so and do not provide support for that use case.

Installation of Grafana on other operating systems is possible, but not supported.

Hardware recommendations

Grafana does not use a lot of resources and is very lightweight in use of memory and CPU.

Minimum recommended memory: 255 MB Minimum recommended CPU: 1

Some features might require more memory or CPUs. Features require more resources include:

Supported databases

Grafana requires a database to store its configuration data, such as users, data sources, and dashboards. The exact requirements depend on the size of the Grafana installation and features used.

Grafana supports the following databases:

SQLite
MySQL
PostgreSQL

By default, Grafana installs with and uses SQLite, which is an embedded database stored in the Grafana installation location.

NOTE: PostgreSQL versions 9.5.18, 9.4.23, 9.6.14, 10.9, 11.4, and 12-beta2 are affected by a bug (tracked by the PostgreSQL project as bug #15865) which prevents those versions from being used with Grafana. The bug has been fixed in more recent versions of PostgreSQL.

Supported web browsers

Grafana is supported in the current version of the following browsers. Older versions of these browsers might not be supported, so you should always upgrade to the latest version when using Grafana.

Chrome/Chromium
Firefox
Safari
Microsoft Edge
Internet Explorer 11 is only fully supported in Grafana versions prior to v6.0.

Note: Always enable JavaScript in your browser. Running Grafana without JavaScript enabled in the browser is not supported.

Run Grafana Docker image

Wed, 15 Apr 2026 19:44:45 +0000

Run Grafana Docker image

You can install and run Grafana using the official Docker container. The official Grafana Docker image comes in two variants: Alpine and Ubuntu.

This page also contains important information about migrating from earlier Docker container versions.

Alpine image (recommended)

grafana/grafana:<version>

This is the default image. This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images, and thus leads to slimmer and more secure images.

This variant is highly recommended when security and final image size being as small as possible is desired. The main caveat to note is that it does use musl libc instead of glibc and friends, so certain software might run into issues depending on the depth of their libc requirements. However, most software doesn’t have an issue with this, so this variant is usually a very safe choice.

Note: The grafana/grafana:<version> image was based on Ubuntu before version 6.4.0.

Ubuntu image

grafana/grafana:<version>-ubuntu

This image is based on Ubuntu, available in the Ubuntu official image. This is an alternative image for those who prefer an Ubuntu based image and/or who are dependent on certain tooling not available for Alpine.

Note: The grafana/grafana:<version>-ubuntu image is available for Grafana version 6.5.0 and later.

Run Grafana

You can run the latest Grafana version, run a specific version, or run an unstable version based on the master branch of the grafana/grafana GitHub repository.

Run the latest stable version of Grafana

Note: If you are on a Linux system, you might need to add sudo before the command.

docker run -d -p 3000:3000 grafana/grafana

Run a specific version of Grafana

Note: If you are on a Linux system, you might need to add sudo before the command.

docker run -d -p 3000:3000 --name grafana grafana/grafana:<version number>

Example:

docker run -d -p 3000:3000 --name grafana grafana/grafana:6.5.0

Run the Grafana master branch

For every successful build of the master branch, we update the grafana/grafana:master and grafana/grafana:master-ubuntu tags. Additionally, two new tags are created, grafana/grafana-dev:master-<commit hash> and grafana/grafana-dev:master-<commit hash>-ubuntu, which includes the hash of the Git commit that was built. Use these to get access to the latest master builds of Grafana.

When running Grafana master in production, we strongly recommend that you use the grafana/grafana-dev:master-<commit hash> tag. This tag guarantees that you use a specific version of Grafana instead of whatever was the most recent commit at the time.

For a list of available tags, check out grafana/grafana and grafana/grafana-dev.

Install plugins in the Docker container

You can install official and community plugins listed on the Grafana plugins page or from a custom URL.

Install official and community Grafana plugins

Pass the plugins you want installed to Docker with the GF_INSTALL_PLUGINS environment variable as a comma-separated list. This sends each plugin name to grafana-cli plugins install ${plugin} and installs them when Grafana starts.

docker run -d \
-p 3000:3000 \
--name=grafana \
-e "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
grafana/grafana

If you need to specify the version of a plugin, then you can add it to the GF_INSTALL_PLUGINS environment variable. Otherwise, the latest will be assumed. For example: -e "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5".

Install plugins from other sources

Only available in Grafana v5.3.1 and later.

You can install plugins from custom URLs by specifying the URL like this: GF_INSTALL_PLUGINS=<url to plugin zip>;<plugin name>.

docker run -d \
-p 3000:3000 \
--name=grafana \
-e "GF_INSTALL_PLUGINS=http://plugin-domain.com/my-custom-plugin.zip;custom-plugin" \
grafana/grafana

Build and run a Docker image with pre-installed plugins

You can build your own customized image that includes plugins. This saves time if you are creating multiple images and you want them all to have the same plugins installed on build.

In the Grafana GitHub repository there is a folder called custom/ which includes two Dockerfiles, Dockerfile and ubuntu.Dockerfile, that can be used to build a custom Grafana image. It accepts GRAFANA_VERSION, GF_INSTALL_PLUGINS, and GF_INSTALL_IMAGE_RENDERER_PLUGIN as build arguments.

Build with pre-installed plugins

If you need to specify the version of a plugin, you can add it to the GF_INSTALL_PLUGINS build argument. Otherwise, the latest will be assumed. For example: --build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5"

Example of how to build and run:

cd custom
docker build \
--build-arg "GRAFANA_VERSION=latest" \
--build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
-t grafana-custom -f Dockerfile .

docker run -d -p 3000:3000 --name=grafana grafana-custom

Replace Dockerfile in above example with ubuntu.Dockerfile to build a custom Ubuntu based image (Grafana v6.5+).

Build with Grafana Image Renderer plugin pre-installed

Only available in Grafana v6.5 and later. This is experimental.

The Grafana Image Renderer plugin does not currently work if it is installed in Grafana Docker image. You can build a custom Docker image by using the GF_INSTALL_IMAGE_RENDERER_PLUGIN build argument. This installs additional dependencies needed for the Grafana Image Renderer plugin to run.

Example of how to build and run:

cd custom
docker build \
--build-arg "GRAFANA_VERSION=latest" \
--build-arg "GF_INSTALL_IMAGE_RENDERER_PLUGIN=true" \
-t grafana-custom -f Dockerfile .

docker run -d -p 3000:3000 --name=grafana grafana-custom

Replace Dockerfile in above example with ubuntu.Dockerfile to build a custom Ubuntu-based image (Grafana v6.5+).

Migrate from previous Docker containers versions

This section contains important information if you want to migrate from previous Grafana container versions to a more current one.

Migrate to v6.5 or later

Grafana Docker image now comes in two variants, one Alpine based and one Ubuntu based, see Image Variants for details.

Migrate to v6.4 or later

Grafana Docker image was changed to be based on Alpine instead of Ubuntu.

Migrate to v5.1 or later

The Docker container for Grafana has seen a major rewrite for 5.1.

Important changes

File ownership is no longer modified during startup with chown.
Default user ID is now 472 instead of 104.
Removed the following implicit volumes:
- /var/lib/grafana
- /etc/grafana
- /var/log/grafana

Removal of implicit volumes

Previously /var/lib/grafana, /etc/grafana and /var/log/grafana were defined as volumes in the Dockerfile. This led to the creation of three volumes each time a new instance of the Grafana container started, whether you wanted it or not.

You should always be careful to define your own named volume for storage, but if you depended on these volumes, then you should be aware that an upgraded container will no longer have them.

Warning: When migrating from an earlier version to 5.1 or later using Docker compose and implicit volumes, you need to use docker inspect to find out which volumes your container is mapped to so that you can map them to the upgraded container as well. You will also have to change file ownership (or user) as documented below.

User ID changes

In Grafana v5.1, we changed the ID of the Grafana user. Unfortunately this means that files created prior to v5.1 won’t have the correct permissions for later versions. We made this change so that it would be more likely that the Grafana users ID would be unique to Grafana. For example, on Ubuntu 16.04 104 is already in use by the syslog user.

Version	User	User ID
< 5.1	grafana	104

= 5.1 | grafana | 472

There are two possible solutions to this problem. Either you start the new container as the root user and change ownership from 104 to 472, or you start the upgraded container as user 104.

Run Docker as a different user

docker run --user 104 --volume "<your volume mapping here>" grafana/grafana:5.1.0

Specify a user in docker-compose.yml

version: "2"

services:
  grafana:
    image: grafana/grafana:5.1.0
    ports:
      - 3000:3000
    user: "104"

Modify permissions

The commands below run bash inside the Grafana container with your volume mapped in. This makes it possible to modify the file ownership to match the new container. Always be careful when modifying permissions.

$ docker run -ti --user root --volume "<your volume mapping here>" --entrypoint bash grafana/grafana:5.1.0

# in the container you just started:
chown -R root:root /etc/grafana && \
chmod -R a+r /etc/grafana && \
chown -R grafana:grafana /var/lib/grafana && \
chown -R grafana:grafana /usr/share/grafana

Next steps

Refer to the Getting Started guide for information about logging in, setting up data sources, and so on.

Configure Docker image

Refer to Configure a Grafana Docker image page for details on options for customizing your environment, logging, database, and so on.

Configure Grafana

Refer to the Configuration page for details on options for customizing your environment, logging, database, and so on.

Security

Wed, 15 Apr 2026 19:44:45 +0000

Security

If you run non-Grafana web services on your Grafana server or within its local network, then they might be vulnerable to exploitation through the Grafana data source proxy or other methods.

To prevent this type of exploitation from happening, we recommend that you apply one or more of the precautions listed below.

Limit IP addresses/hostnames for data source URL

You can configure Grafana to only allow certain IP addresses or hostnames to be used as data source URLs and proxied through the Grafana data source proxy. Refer to data_source_proxy_whitelist for usage instructions.

Firewall rules

Configure a firewall to restrict Grafana from making network requests to sensitive internal web services.

There are many firewall tools available, refer to the documentation for your specific security tool. For example, Linux users can use iptables.

Proxy server

Require all network requests being made by Grafana to go through a proxy server.

Limit Viewer query permissions

Users with the Viewer role can enter any possible query in any of the data sources available in the organization, not just the queries that are defined on the dashboards for which the user has Viewer permissions.

For example: In a Grafana instance with one data source, one dashboard, and one panel that has one query defined, you might assume that a Viewer can only see the result of the query defined in that panel. Actually, the Viewer has access to send any query to the data source. With a command-line tool like curl (there are lots of tools for this), the Viewer can make their own query to the data source and potentially access sensitive data.

To address this vulnerability, you can restrict data source query access in the following ways:

Create multiple data sources with some restrictions added in data source config that restrict access (like database name or credentials). Then use the Data Source Permissions Enterprise feature to restrict user access to the data source in Grafana.
Create a separate Grafana organization, and in that organization, create a separate data source. Make sure the data source has some option/user/credentials setting that limits access to a subset of the data. Not all data sources have an option to limit access.

Troubleshooting

Wed, 15 Apr 2026 19:44:45 +0000

Troubleshooting

This page lists some useful tools to help troubleshoot common Grafana issues.

Visualization and query issues

The most common problems are related to the query and response from your data source. Even if it looks like a bug or visualization issue in Grafana, it is almost always a problem with the data source query or the data source response.

To check this you should use query inspector, which was added in Grafana 4.5. The query inspector shows query requests and responses. Refer to the data source page for more information.

For more on the query inspector read the Grafana Community article Using Grafana’s Query Inspector to troubleshoot issues. For older versions of Grafana, refer to the How troubleshoot metric query issue article.

Logging

If you encounter an error or problem, then you can check the Grafana server log. Usually located at /var/log/grafana/grafana.log on Unix systems or in <grafana_install_dir>/data/log on other platforms and manual installations.

You can enable more logging by changing log level in the Grafana configuration file.

Diagnostics

The grafana-server process can be instructed to enable certain diagnostics when it starts. This can be helpful when investigating certain performance problems. It’s not recommended to have these enabled by default.

Profiling

The grafana-server can be started with the arguments -profile to enable profiling and -profile-port to override the default HTTP port (6060) where the pprof debugging endpoints will be available, e.g.

./grafana-server -profile -profile-port=8080

Note that pprof debugging endpoints are served on a different port than the Grafana HTTP server.

You can configure or override profiling settings using environment variables:

export GF_DIAGNOSTICS_PROFILING_ENABLED=true
export GF_DIAGNOSTICS_PROFILING_PORT=8080

Refer to Go command pprof for more information about how to collect and analyze profiling data.

Server side image rendering (RPM-based Linux)

Server side image (png) rendering is a feature that is optional but very useful when sharing visualizations, for example in alert notifications.

If the image is missing text make sure you have font packages installed.

sudo yum install fontconfig
sudo yum install freetype*
sudo yum install urw-fonts

Tracing

The grafana-server can be started with the arguments -tracing to enable tracing and -tracing-file to override the default trace file (trace.out) where trace result is written to. For example:

./grafana-server -tracing -tracing-file=/tmp/trace.out

You can configure or override profiling settings using environment variables:

export GF_DIAGNOSTICS_TRACING_ENABLED=true
export GF_DIAGNOSTICS_TRACING_FILE=/tmp/trace.out

View the trace in a web browser (Go required to be installed):

go tool trace <trace file>
2019/11/24 22:20:42 Parsing trace...
2019/11/24 22:20:42 Splitting trace...
2019/11/24 22:20:42 Opening browser. Trace viewer is listening on http://127.0.0.1:39735

See Go command trace for more information about how to analyze trace files.

FAQs

Check out the FAQ section on the Grafana Community page for answers to frequently asked questions.

Upgrade Grafana

Wed, 15 Apr 2026 19:44:45 +0000

Upgrade Grafana

We recommend that you upgrade Grafana often to stay up to date with the latest fixes and enhancements. In order to make this a reality, Grafana upgrades are backward compatible and the upgrade process is simple and quick.

Upgrading is generally safe (between many minor and one major version) and dashboards and graphs will look the same. There may be minor breaking changes in some edge cases, which are outlined in the Release Notes and Changelog

Backup

We recommend that you backup a few things in case you have to rollback the upgrade.

Installed plugins - Back them up before you upgrade them in case you want to rollback the Grafana version and want to get the exact same versions you where running before the upgrade.
Configuration files do not need to be backed up. However, you might want to in case you add new config options after upgrade and then rollback.

Database backup

Before upgrading it can be a good idea to backup your Grafana database. This will ensure that you can always rollback to your previous version. During startup, Grafana will automatically migrate the database schema (if there are changes or new tables). Sometimes this can cause issues if you later want to downgrade.

sqlite

If you use sqlite you only need to make a backup of your grafana.db file. This is usually located at /var/lib/grafana/grafana.db on Unix systems. If you are unsure what database you use and where it is stored check you grafana configuration file. If you installed grafana to custom location using a binary tar/zip it is usually in <grafana_install_dir>/data.

mysql

backup:
> mysqldump -u root -p[root_password] [grafana] > grafana_backup.sql

restore:
> mysql -u root -p grafana < grafana_backup.sql

postgres

backup:
> pg_dump grafana > grafana_backup

restore:
> psql grafana < grafana_backup

Ubuntu or Debian

You can upgrade Grafana by following the same procedure as when you installed it.

Upgrade Debian package

If you installed Grafana by downloading a Debian package (.deb), then you can execute the same dpkg -i command but with the new package. It will upgrade your Grafana installation.

Go to the download page for the latest download links.

wget <debian package url>
sudo apt-get install -y adduser libfontconfig1
sudo dpkg -i grafana_<version>_amd64.deb

Upgrade from APT repository

If you installed Grafana from our APT repository, then Grafana will automatically update when you run apt-get upgrade to upgrade all system packages.

sudo apt-get update
sudo apt-get upgrade

Upgrade from binary .tar file

If you downloaded the binary .tar.gz package, then you can just download and extract the new package and overwrite all your existing files. However, this might overwrite your config changes.

We recommend that you save your custom config changes in a file named <grafana_install_dir>/conf/custom.ini. This allows you to upgrade Grafana without risking losing your configuration changes.

Centos / RHEL

If you installed Grafana by downloading an RPM package you can just follow the same installation guide and execute the same yum install or rpm -i command but with the new package. It will upgrade your Grafana installation.

If you used our YUM repository:

sudo yum update grafana

Docker

This just an example, details depend on how you configured your grafana container.

docker pull grafana/grafana
docker stop my-grafana-container
docker rm my-grafana-container
docker run -d --name=my-grafana-container --restart=always -v /var/lib/grafana:/var/lib/grafana grafana/grafana

Windows

If you downloaded the Windows binary package you can just download a newer package and extract to the same location (and overwrite the existing files). This might overwrite your config changes. We recommend that you save your config changes in a file named <grafana_install_dir>/conf/custom.ini as this will make upgrades easier without risking losing your config changes.

Update plugins

After you have upgraded, we strongly recommend that you update all your plugins as a new version of Grafana can make older plugins stop working properly.

You can update all plugins using

grafana-cli plugins update-all

Upgrading from 1.x

Migrating from 1.x to 2.x

Upgrading from 2.x

We are not aware of any issues upgrading directly from 2.x to 4.x but to be on the safe side go via 3.x => 4.x.

Upgrading to v5.0

The dashboard grid layout engine has changed. All dashboards will be automatically upgraded to new positioning system when you load them in v5. Dashboards saved in v5 will not work in older versions of Grafana. Some external panel plugins might need to be updated to work properly.

For more details on the new panel positioning system, click here

Upgrading to v5.2

One of the database migrations included in this release will update all annotation timestamps from second to millisecond precision. If you have a large amount of annotations the database migration may take a long time to complete which may cause problems if you use systemd to run Grafana.

We’ve got one report where using systemd, PostgreSQL and a large amount of annotations (table size 1645mb) took 8-20 minutes for the database migration to complete. However, the grafana-server process was killed after 90 seconds by systemd. Any database migration queries in progress when systemd kills the grafana-server process continues to execute in database until finished.

If you’re using systemd and have a large amount of annotations consider temporary adjusting the systemd TimeoutStartSec setting to something high like 30m before upgrading.

Upgrading to v6.0

If you have text panels with script tags they will no longer work due to a new setting that per default disallow unsanitized HTML. Read more here about this new setting.

Authentication and security

If you are using Grafana’s builtin, LDAP (without Auth Proxy) or OAuth authentication all users will be required to login upon the next visit after the upgrade.

If you have cookie_secure set to true in the session section you probably want to change the cookie_secure to true in the security section as well. Ending up with a configuration like this:

[session]
cookie_secure = true

[security]
cookie_secure = true

The login_remember_days, cookie_username and cookie_remember_name settings in the security section are no longer being used so they’re safe to remove.

If you have login_remember_days configured to 0 (zero) you should change your configuration to this to accomplish similar behavior, i.e. a logged in user will maximum be logged in for 1 day until being forced to login again:

[auth]
login_maximum_inactive_lifetime_days = 1
login_maximum_lifetime_days = 1

The default cookie name for storing the auth token is grafana_session. you can configure this with login_cookie_name in [auth] settings.

Upgrading to v6.2

Ensure encryption of data source secrets

Data sources store passwords and basic auth passwords in secureJsonData encrypted (AES-256 in CFB mode) by default. Existing data source will keep working with unencrypted passwords. If you want to migrate to encrypted storage for your existing data sources you can do that by:

For data sources created through UI, you need to go to data source config, re enter the password or basic auth password and save the data source.
For data sources created by provisioning, you need to update your config file and use secureJsonData.password or secureJsonData.basicAuthPassword field. See provisioning docs for example of current configuration.

Embedding Grafana

If you’re embedding Grafana in a <frame>, <iframe>, <embed> or <object> on a different website it will no longer work due to a new setting that per default instructs the browser to not allow Grafana to be embedded. Read more here about this new setting.

Session storage is no longer used

In 6.2 we completely removed the backend session storage since we replaced the previous login session implementation with an auth token. If you are using Auth proxy with LDAP an shared cached is used in Grafana so you might want configure [remote_cache] instead. If not Grafana will fallback to using the database as an shared cache.

Upgrading Elasticsearch to v7.0+

The semantics of max concurrent shard requests changed in Elasticsearch v7.0, see release notes for reference.

If you upgrade Elasticsearch to v7.0+ you should make sure to update the data source configuration in Grafana so that version is 7.0+ and max concurrent shard requests properly configured. 256 was the default in pre v7.0 versions. In v7.0 and above 5 is the default.

Upgrading to v6.4

Annotations database migration

One of the database migrations included in this release will merge multiple rows used to represent an annotation range into a single row. If you have a large number of region annotations the database migration may take a long time to complete. See Upgrading to v5.2 for tips on how to manage this process.

Docker

Grafana’s docker image is now based on Alpine instead of Ubuntu.

Plugins that need updating

Splunk

Upgrading to v6.5

Pre Grafana 6.5.0, the CloudWatch datasource used the GetMetricStatistics API for all queries that did not have an ´id´ and did not have an ´expression´ defined in the query editor. The GetMetricStatistics API has a limit of 400 transactions per second (TPS). In this release, all queries use the GetMetricData API which has a limit of 50 TPS and 100 metrics per transaction. We expect this transition to be smooth for most of our users, but in case you do face throttling issues we suggest you increase the TPS quota. To do that, please visit the AWS Service Quotas console. For more details around CloudWatch API limits, see CloudWatch docs.

Each request to the GetMetricData API can include 100 queries. This means that each panel in Grafana will only issue one GetMetricData request, regardless of the number of query rows that are present in the panel. Consequently as it is no longer possible to set HighRes on a per query level anymore, this switch is now removed from the query editor. High resolution can still be achieved by choosing a smaller minimum period in the query editor.

The handling of multi-valued template variables in dimension values has been changed in Grafana 6.5. When a multi template variable is being used, Grafana will generate a search expression. In the GetMetricData API, expressions are limited to 1024 characters, so it might be the case that this limit is reached when a multi-valued template variable that has a lot of values is being used. If this is the case, we suggest you start using * wildcard as dimension value instead of a multi-valued template variable.

Upgrading to v6.6

The Generic OAuth setting send_client_credentials_via_post, used for supporting non-compliant providers, has been removed. From now on, Grafana will automatically detect if credentials should be sent as part of the URL or request body for a specific provider. The result will be remembered and used for additional OAuth requests for that provider.

Chrome 80 treats cookies as SameSite=Lax by default if no SameSite attribute is specified, see https://www.chromestatus.com/feature/5088147346030592.

Due to this change in Chrome, the [security] setting cookie_samesite configured to none now renders cookies with SameSite=None attribute compared to before where no SameSite attribute was added to cookies. To get the old behavior, use value disabled instead of none, see cookie_samesite in Configuration for more information.

Note: There is currently a bug affecting Mac OSX and iOS that causes SameSite=None cookies to be treated as SameSite=Strict and therefore not sent with cross-site requests, see https://bugs.webkit.org/show_bug.cgi?id=198181 for details. Until this is fixed, SameSite=None might not work properly on Safari.

This version of Chrome also rejects insecure SameSite=None cookies. See https://www.chromestatus.com/feature/5633521622188032 for more information. Make sure that you change the [security] setting cookie_secure to true and use HTTPS when cookie_samesite is configured to none, otherwise authentication in Grafana won’t work properly.

Upgrading to v7.0

PhantomJS removed

PhantomJS was deprecated in Grafana v6.4 and starting from Grafana v7.0.0, all PhantomJS support has been removed. This means that Grafana no longer ships with a built-in image renderer, and we advise you to install the Grafana Image Renderer plugin.

Dashboard minimum refresh interval enforced

A global minimum dashboard refresh interval is now enforced and defaults to 5 seconds. Read more here about this setting.

Backend plugins

Grafana now requires backend plugins to be signed. If a backend plugin is not signed Grafana will not load/start it. This is an additional security measure to make sure backend plugin binaries and files haven’t been tampered with. All Grafana Labs authored backend plugins, including Enterprise plugins, are now signed. It’s possible to allow unsigned plugins using a configuration setting, but is something we strongly advise against doing. Read more here about this setting.

Starting from Grafana v7.0.0, the cookie path does not include the trailing slash if Grafana is served from a subpath in order to align with RFC 6265. However, stale session cookies (set before the upgrade) can result in unsuccessful logins because they can not be deleted during the standard login phase due to the changed cookie path. Therefore users experiencing login problems are advised to manually delete old session cookies, or administrators can fix this for all users by changing the login_cookie_name, so the old cookie would get ignored.