Installation

This guide explains how to install Prometheus Pushgateway, run it as a service, and configure Prometheus to scrape it. Pushgateway is useful when ephemeral or batch jobs need to push metrics for Prometheus to collect later.

Prerequisites

A Linux host (or another OS) with network access from your Prometheus server.
wget or curl for downloading the release.
systemd (recommended) if you want Pushgateway to run as a managed service.

Download the Pushgateway binary from the official GitHub releases page: https://github.com/prometheus/pushgateway/releases. Releases include prebuilt binaries for Darwin, Linux, and Windows.

A screenshot of the Prometheus "pushgateway" download page showing version 1.4.3. It displays a table of downloadable files for Darwin, Linux and Windows with file sizes and SHA256 checksums.

Quick install and test (Linux example)

Download and extract the release (example: v1.4.3, Linux amd64):

# download the release (example: v1.4.3 Linux amd64)
wget https://github.com/prometheus/pushgateway/releases/download/v1.4.3/pushgateway-1.4.3.linux-amd64.tar.gz

# extract the archive
tar xvf pushgateway-1.4.3.linux-amd64.tar.gz

# move into the extracted directory
cd pushgateway-1.4.3.linux-amd64

Start Pushgateway directly for a quick smoke test (listens on port 9091 by default):

./pushgateway

Verify the metrics endpoint that Prometheus will scrape:

curl http://localhost:9091/metrics

Example trimmed output:

# HELP process_start_time_seconds Start time of the process since unix epoch in seconds.
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1.66572119292e+09
# HELP process_virtual_memory_bytes Virtual memory size in bytes.
# TYPE process_virtual_memory_bytes gauge
process_virtual_memory_bytes 7.3271296e+08
# HELP pushgateway_build_info A metric with a constant '1' value labeled by version, revision, branch, and goversion from which pushgateway was built.
# TYPE pushgateway_build_info gauge
pushgateway_build_info{branch="HEAD",goversion="go1.18.2",revision="f9dc1c8664050edbc75916c3664be1df595a1958",version="1.4.3"} 1

Install Pushgateway as a systemd service (recommended for production)

Running Pushgateway under systemd makes it easier to manage, restart on failure, and control permissions.

Create a dedicated system user and copy the binary:

# create a system user for the service (no login shell, no home)
sudo useradd --no-create-home --shell /bin/false --system pushgateway

# copy the pushgateway binary to /usr/local/bin
sudo cp pushgateway /usr/local/bin/

# set ownership and permissions
sudo chown pushgateway:pushgateway /usr/local/bin/pushgateway
sudo chmod 0755 /usr/local/bin/pushgateway

Create the systemd unit file /etc/systemd/system/pushgateway.service with the following content:

[Unit]
Description=Prometheus Pushgateway
Wants=network-online.target
After=network-online.target

[Service]
User=pushgateway
Group=pushgateway
Type=simple
ExecStart=/usr/local/bin/pushgateway

[Install]
WantedBy=multi-user.target

Reload systemd, start, enable, and check status:

sudo systemctl daemon-reload
sudo systemctl start pushgateway
sudo systemctl enable pushgateway
sudo systemctl status pushgateway

If your host has a firewall, allow port 9091 or configure your firewall rules accordingly.

When exposing Pushgateway, ensure only trusted processes can push metrics. The Pushgateway accepts pushed metrics and preserves labels; untrusted pushers may inject or overwrite labels. Use network controls and authentication where necessary.

Common commands reference

Action	Command / Example
Download & extract	`wget https://github.com/prometheus/pushgateway/releases/download/v1.4.3/pushgateway-1.4.3.linux-amd64.tar.gz` then `tar xvf pushgateway-1.4.3.linux-amd64.tar.gz`
Run locally	`./pushgateway`
Check metrics	`curl http://localhost:9091/metrics`
Manage systemd service	`sudo systemctl start\|stop\|status pushgateway`

Configure Prometheus to scrape Pushgateway

Add a scrape job to your prometheus.yml. The key setting is honor_labels: true. Many jobs that push metrics to Pushgateway include their own job and instance labels; by default Prometheus would overwrite those labels with the scrape job’s labels. honor_labels: true preserves the labels provided by pushers. Example prometheus.yml snippet:

scrape_configs:
  - job_name: pushgateway
    honor_labels: true
    static_configs:
      - targets: ["192.168.1.168:9091"]

Setting honor_labels: true ensures metrics pushed to the Pushgateway retain the original labels (for example job and instance) provided by the pushing jobs rather than being overwritten by the scrape job’s labels.

With this configuration:

Multiple jobs can push metrics to the Pushgateway and set identifying labels.
Prometheus will scrape the Pushgateway and preserve those label values, allowing metrics to reflect their true source.

Troubleshooting & tips

If metrics appear missing or labels are different than expected, check that the clients pushing metrics set the labels as intended and that honor_labels is enabled.
If Pushgateway fails to start under systemd, inspect journalctl -u pushgateway for logs.
For secure or multi-tenant setups, consider using network-level controls, authentication proxies, or restricting who can push metrics.

Links and references

Prometheus Pushgateway releases: https://github.com/prometheus/pushgateway/releases
Prometheus documentation: https://prometheus.io/docs/

Introduction

Observability Fundamentals

Prometheus Fundamentals

PromQL

Dashboarding & Visualization

Application Instrumentation

Service Discovery

Push Gateway

Alerting

Monitoring Kubernetes

Conclusion

Scaling & Long Term Storage

Prerequisites

Quick install and test (Linux example)

Install Pushgateway as a systemd service (recommended for production)

Common commands reference

Configure Prometheus to scrape Pushgateway

Troubleshooting & tips

Links and references

Watch Video

​Prerequisites

​Quick install and test (Linux example)

​Install Pushgateway as a systemd service (recommended for production)

​Common commands reference

​Configure Prometheus to scrape Pushgateway

​Troubleshooting & tips

​Links and references

Watch Video

Prerequisites

Quick install and test (Linux example)

Install Pushgateway as a systemd service (recommended for production)

Common commands reference

Configure Prometheus to scrape Pushgateway

Troubleshooting & tips

Links and references