---
title: Install
weight: 1150
description: Instructions for installing etcd from pre-built binaries or from source.
minGoVers: 1.21
---

## Requirements

Before installing etcd, see the following pages:

- [Supported platforms][]
- [Hardware recommendations][]

## Install pre-built binaries

The easiest way to install etcd is from pre-built binaries:

 1. Download the compressed archive file for your platform from [Releases][],
    choosing release [{{< param git_version_tag >}}][tagged-release] or later.
 2. Unpack the archive file. This results in a directory containing the binaries.
 3. Add the executable binaries to your path. For example, rename and/or move
    the binaries to a directory in your path (like `/usr/local/bin`), or add the
    directory created by the previous step to your path.
 4. From a shell, test that `etcd` is in your path:

    ```sh
    $ etcd --version
    etcd Version: {{< psubstr git_version_tag 1 >}}
    ...
    ```

## Build from source

If you have [Go version {{< param minGoVers >}}+][go], you can build etcd from
source by following these steps:

 1. [Download the etcd repo as a zip file][download] and unzip it, or clone the
    repo using the following command.

    ```sh
    $ git clone -b {{< param git_version_tag >}} https://github.com/etcd-io/etcd.git
    ```
    To build from `{{< param github_branch >}}@HEAD`, omit the `-b  {{< param
    git_version_tag >}}` flag.

 2. Change directory:

    ```sh
    $ cd etcd
    ```
 3. Run the build script:

    ```sh
    $ ./scripts/build.sh
    ```

    The binaries are under the `bin` directory.

 4. Add the full path to the `bin` directory to your path, for example:

    ```sh
    $ export PATH="$PATH:`pwd`/bin"
    ```

 5. Test that `etcd` is in your path:

    ```sh
    $ etcd --version
    ```

## Installation via OS packages

{{% alert title="Warning" color="warning" %}}

etcd installations through OS package managers can deliver outdated versions since they are not being automatically maintained nor officially supported by etcd project. Therefore use OS packages with caution.*

{{% /alert %}}

There are various ways of installing etcd on different operating systems and these are just some examples how it can be done.

### MacOS (Homebrew)

1. Update homebrew:
```sh
$ brew update
```

2. Install etcd:
```sh
$ brew install etcd
```

3. Verify install
```sh
$ etcd --version
```

## Linux

{{% alert title="Warning" color="warning" %}}

Although installing etcd through many major Linux distributions' official repositories and package managers is possible, the published versions can be significantly outdated. So, installing this way is strongly discouraged.

{{% /alert %}}

The recommended way to install etcd on Linux is either through [pre-built binaries](#install-pre-built-binaries) or by using Homebrew.

### Homebrew on Linux

[Homebrew can run on Linux], and can provide recent software versions.

- Prerequisites
  - Update Homebrew:

    ```sh
    $ brew update
    ```

- Procedure
  - Install using `brew`:

    ```sh
    $ brew install etcd
    ```

- Result
  - Verify installation by getting the version:

    ```sh
    $ etcd --version
    etcd Version: {{< psubstr git_version_tag 1 >}}
    ...
    ```

## Docker

etcd uses [`gcr.io/etcd-development/etcd`](https://gcr.io/etcd-development/etcd) as a
primary container registry, and [`quay.io/coreos/etcd`](https://quay.io/coreos/etcd) as
secondary.

To run etcd using Docker:

```sh
ETCD_VER={{< param git_version_tag >}}

rm -rf /tmp/etcd-data.tmp && mkdir -p /tmp/etcd-data.tmp && \
  docker rmi gcr.io/etcd-development/etcd:${ETCD_VER} || true && \
  docker run \
  -p 2379:2379 \
  -p 2380:2380 \
  --mount type=bind,source=/tmp/etcd-data.tmp,destination=/etcd-data \
  --name etcd-gcr-${ETCD_VER} \
  gcr.io/etcd-development/etcd:${ETCD_VER} \
  /usr/local/bin/etcd \
  --name s1 \
  --data-dir /etcd-data \
  --listen-client-urls http://0.0.0.0:2379 \
  --advertise-client-urls http://0.0.0.0:2379 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --initial-advertise-peer-urls http://0.0.0.0:2380 \
  --initial-cluster s1=http://0.0.0.0:2380 \
  --initial-cluster-token tkn \
  --initial-cluster-state new \
  --log-level info \
  --logger zap \
  --log-outputs stderr

docker exec etcd-gcr-${ETCD_VER} /usr/local/bin/etcd --version
docker exec etcd-gcr-${ETCD_VER} /usr/local/bin/etcdctl version
docker exec etcd-gcr-${ETCD_VER} /usr/local/bin/etcdutl version
docker exec etcd-gcr-${ETCD_VER} /usr/local/bin/etcdctl endpoint health
docker exec etcd-gcr-${ETCD_VER} /usr/local/bin/etcdctl put foo bar
docker exec etcd-gcr-${ETCD_VER} /usr/local/bin/etcdctl get foo
```

## Installation as part of Kubernetes installation

- [Running etcd as a Kubernetes StatefulSet][]

## Installation check

For a slightly more involved sanity check of your installation, see
[Quickstart][].

[download]: https://github.com/etcd-io/etcd/archive/{{< param git_version_tag >}}.zip
[go]: https://golang.org/doc/install
[Hardware recommendations]: {{< relref "op-guide/hardware" >}}
[Quickstart]: {{< relref "quickstart" >}}
[Running etcd as a Kubernetes StatefulSet]: {{< relref "op-guide/kubernetes" >}}
[releases]: https://github.com/etcd-io/etcd/releases/
[tagged-release]: https://github.com/etcd-io/etcd/releases/tag/{{< param git_version_tag >}}
[Supported platforms]: {{< relref "op-guide/supported-platform" >}}
[Homebrew can run on Linux]: <https://docs.brew.sh/Homebrew-on-Linux>