---
title: "Install Promtail | Grafana Loki documentation"
description: "Installation instructions for the Promtail client."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Install Promtail

> Caution
> 
> Promtail has been deprecated and is in Long-Term Support (LTS) through February 28, 2026. Promtail will reach an End-of-Life (EOL) on March 2, 2026. You can find migration resources [here](/docs/alloy/latest/set-up/migrate/from-promtail/).

Promtail is distributed as a binary, in a Docker container, or there is a Helm chart to install it in a Kubernetes cluster.

## Install the binary

Every Grafana Loki release includes binaries for Promtail which can be found on the [Releases page](https://github.com/grafana/loki/releases) as part of the release assets.

## Install using APT or RPM package manager

See the instructions [here](/docs/loki/v3.6.x/setup/install/local/#install-using-apt-or-rpm-package-manager).

## Install using Docker

1. Make sure to modify the tag to the most recent version.
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   docker pull grafana/promtail:3.6.0
   ```
2. Create your Promtail configuration file in a file called `promtail-config.yaml`. Refer to the [Promtail configuration reference](/docs/loki/v3.6.x/send-data/promtail/configuration/) for more details.
3. Note that you will need to replace `<local-path>` in the commands with your local path and may need to update the release version to match the current release.
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   docker run -v <local-path>:/mnt/config -v /var/log:/var/log --link loki grafana/promtail:3.6.0 --config.file=/mnt/config/promtail-config.yaml
   ```

## Install on MacOS with Homebrew

1. If necessary, install [Homebrew](https://brew.sh/).
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```
2. Update Homebrew.
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   brew update
   ```
3. Navigate to the [homebrew page for Promtail](https://formulae.brew.sh/formula/promtail).
4. To install Promtail, run the following command:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   brew install promtail
   ```
5. Check that installation was successful.
   
   1. Check that promtail exists in its install directory.
      
      Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
      
      ```bash
      which promtail
      ```
   2. Run promtail
      
      Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
      
      ```bash
      promtail
      ```

## Install using Helm

1. Make sure that Helm is installed. See [Installing Helm](https://helm.sh/docs/intro/install/).
2. Then you can add Grafana’s chart repository to Helm:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   helm repo add grafana https://grafana.github.io/helm-charts
   ```
3. Update the chart repository:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   helm repo update
   ```
4. Create the configuration file `values.yaml`. The example below illustrates a connection to the locally deployed loki server:
   
   YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```yaml
   config:
   # publish data to loki
     clients:
       - url: http://loki-gateway/loki/api/v1/push
         tenant_id: 1
   ```
5. Finally, Promtail can be deployed with:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   # The default helm configuration deploys promtail as a daemonSet (recommended)
   helm upgrade --values values.yaml --install promtail grafana/promtail
   ```

## Install as Kubernetes daemonSet (recommended)

A `DaemonSet` will deploy Promtail on every node within a Kubernetes cluster.

The DaemonSet deployment works well at collecting the logs of all containers within a cluster. It’s the best solution for a single-tenant model. Replace `{YOUR_LOKI_ENDPOINT}` with your Loki endpoint.

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
--- # Daemonset.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: promtail-daemonset
spec:
  selector:
    matchLabels:
      name: promtail
  template:
    metadata:
      labels:
        name: promtail
    spec:
      serviceAccount: promtail-serviceaccount
      containers:
      - name: promtail-container
        image: grafana/promtail
        args:
        - -config.file=/etc/promtail/promtail.yaml
        env: 
        - name: 'HOSTNAME' # needed when using kubernetes_sd_configs
          valueFrom:
            fieldRef:
              fieldPath: 'spec.nodeName'
        volumeMounts:
        - name: logs
          mountPath: /var/log
        - name: promtail-config
          mountPath: /etc/promtail
        - mountPath: /var/lib/docker/containers
          name: varlibdockercontainers
          readOnly: true
      volumes:
      - name: logs
        hostPath:
          path: /var/log
      - name: varlibdockercontainers
        hostPath:
          path: /var/lib/docker/containers
      - name: promtail-config
        configMap:
          name: promtail-config
--- # configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: promtail-config
data:
  promtail.yaml: |
    server:
      http_listen_port: 9080
      grpc_listen_port: 0

    clients:
    - url: https://<YOUR_LOKI_ENDPOINT>/loki/api/v1/push

    positions:
      filename: /tmp/positions.yaml
    target_config:
      sync_period: 10s
    scrape_configs:
    - job_name: pod-logs
      kubernetes_sd_configs:
        - role: pod
      pipeline_stages:
        - docker: {}
      relabel_configs:
        - source_labels:
            - __meta_kubernetes_pod_node_name
          target_label: __host__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)
        - action: replace
          replacement: $1
          separator: /
          source_labels:
            - __meta_kubernetes_namespace
            - __meta_kubernetes_pod_name
          target_label: job
        - action: replace
          source_labels:
            - __meta_kubernetes_namespace
          target_label: namespace
        - action: replace
          source_labels:
            - __meta_kubernetes_pod_name
          target_label: pod
        - action: replace
          source_labels:
            - __meta_kubernetes_pod_container_name
          target_label: container
        - replacement: /var/log/pods/*$1/*.log
          separator: /
          source_labels:
            - __meta_kubernetes_pod_uid
            - __meta_kubernetes_pod_container_name
          target_label: __path__

--- # Clusterrole.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: promtail-clusterrole
rules:
  - apiGroups: [""]
    resources:
    - nodes
    - services
    - pods
    verbs:
    - get
    - watch
    - list

--- # ServiceAccount.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: promtail-serviceaccount

--- # Rolebinding.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: promtail-clusterrolebinding
subjects:
    - kind: ServiceAccount
      name: promtail-serviceaccount
      namespace: default
roleRef:
    kind: ClusterRole
    name: promtail-clusterrole
    apiGroup: rbac.authorization.k8s.io
```