Install ClickHouse using Docker

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/getting-started/install/docker.md)

The guide on [Docker Hub](https://hub.docker.com/r/clickhouse/clickhouse-server/)
is reproduced below for convenience. The Docker images available make use of
the official ClickHouse deb packages.

Docker pull command:

```
docker pull clickhouse/clickhouse-server
```

## Versions[​](#versions "Direct link to Versions")

- The `latest` tag points to the latest release of the latest stable branch.
- Branch tags like `22.2` point to the latest release of the corresponding branch.
- Full Version tags like `22.2.3` and `22.2.3.5` point to the corresponding release.
- The tag `head` is built from the latest commit to the default branch.
- Each tag has an optional `-alpine` suffix to reflect that it's built on top of `alpine`.

### Compatibility[​](#compatibility "Direct link to Compatibility")

- The amd64 image requires support for [SSE3 instructions](https://en.wikipedia.org/wiki/SSE3).
  Virtually all x86 CPUs after 2005 support SSE3.
- The arm64 image requires support for the [ARMv8.2-A architecture](https://en.wikipedia.org/wiki/AArch64#ARMv8.2-A) and
  additionally the Load-Acquire RCpc register. The register is optional in version ARMv8.2-A and mandatory in
  [ARMv8.3-A](https://en.wikipedia.org/wiki/AArch64#ARMv8.3-A). Supported in Graviton >=2, Azure and GCP instances.
  Examples for unsupported devices are Raspberry Pi 4 (ARMv8.0-A) and Jetson AGX Xavier/Orin (ARMv8.2-A).
- Since ClickHouse 24.11 Ubuntu images began using `ubuntu:22.04` as its base image. It requires docker version >= `20.10.10`
  containing [patch](https://github.com/moby/moby/commit/977283509f75303bc6612665a04abf76ff1d2468). As a workaround you could
  use `docker run --security-opt seccomp=unconfined` instead, however this has security implications.

## How to use this image[​](#how-to-use-image "Direct link to How to use this image")

### Start server instance[​](#start-server-instance "Direct link to Start server instance")

```
docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
```

By default, ClickHouse will be accessible only via the Docker network. See the networking section below.

By default, starting above server instance will be run as the `default` user without password.

### Connect to it from a native client[​](#connect-to-it-from-native-client "Direct link to Connect to it from a native client")

```
docker run -it --rm --network=container:some-clickhouse-server --entrypoint clickhouse-client clickhouse/clickhouse-server
# OR
docker exec -it some-clickhouse-server clickhouse-client
```

See [ClickHouse client](/docs/interfaces/cli) for more information about ClickHouse client.

### Connect to it using curl[​](#connect-to-it-using-curl "Direct link to Connect to it using curl")

```
echo "SELECT 'Hello, ClickHouse!'" | docker run -i --rm --network=container:some-clickhouse-server buildpack-deps:curl curl 'http://localhost:8123/?query=' -s --data-binary @-
```

See [ClickHouse HTTP Interface](/docs/interfaces/http) for more information about the HTTP interface.

### Stopping / removing the container[​](#stopping-removing-container "Direct link to Stopping / removing the container")

```
docker stop some-clickhouse-server
docker rm some-clickhouse-server
```

### Networking[​](#networking "Direct link to Networking")

Note

the predefined user `default` doesn't have the network access unless the password is set,
see "How to create default database and user on starting" and "Managing `default` user" below

You can expose your ClickHouse running in docker by [mapping a particular port](https://docs.docker.com/config/containers/container-networking/)
from inside the container using host ports:

```
docker run -d -p 18123:8123 -p19000:9000 -e CLICKHOUSE_PASSWORD=changeme --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
echo 'SELECT version()' | curl 'http://localhost:18123/?password=changeme' --data-binary @-
```

Or by allowing the container to use [host ports directly](https://docs.docker.com/network/host/) using `--network=host`
(also allows achieving better network performance):

```
docker run -d --network=host --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
echo 'SELECT version()' | curl 'http://localhost:8123/' --data-binary @-
```

Note

The user default in the example above is available only for the localhost requests

### Volumes[​](#volumes "Direct link to Volumes")

Typically you may want to mount the following folders inside your container to achieve persistency:

- `/var/lib/clickhouse/` - main folder where ClickHouse stores the data
- `/var/log/clickhouse-server/` - logs

```
docker run -d \
    -v "$PWD/ch_data:/var/lib/clickhouse/" \
    -v "$PWD/ch_logs:/var/log/clickhouse-server/" \
    --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
```

You may also want to mount:

- `/etc/clickhouse-server/config.d/*.xml` - files with server configuration adjustments
- `/etc/clickhouse-server/users.d/*.xml` - files with user settings adjustments
- `/docker-entrypoint-initdb.d/` - folder with database initialization scripts (see below).

## Linux capabilities[​](#linear-capabilities "Direct link to Linux capabilities")

ClickHouse has some advanced functionality, which requires enabling several [Linux capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html)

They're optional and can be enabled using the following [docker command-line arguments](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities):

```
docker run -d \
    --cap-add=SYS_NICE --cap-add=NET_ADMIN --cap-add=IPC_LOCK \
    --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
```

For more information see ["Configuring CAP\_IPC\_LOCK and CAP\_SYS\_NICE Capabilities in Docker"](/docs/knowledgebase/configure_cap_ipc_lock_and_cap_sys_nice_in_docker)

## Configuration[​](#configuration "Direct link to Configuration")

The container exposes port 8123 for the [HTTP interface](https://clickhouse.com/docs/interfaces/http_interface/) and port 9000 for the [native client](https://clickhouse.com/docs/interfaces/tcp/).

ClickHouse configuration is represented with a file "config.xml" ([documentation](https://clickhouse.com/docs/operations/configuration_files/))

### Start server instance with custom configuration[​](#start-server-instance-with-custom-config "Direct link to Start server instance with custom configuration")

```
docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 -v /path/to/your/config.xml:/etc/clickhouse-server/config.xml clickhouse/clickhouse-server
```

### Start server as custom user[​](#start-server-custom-user "Direct link to Start server as custom user")

```
# $PWD/data/clickhouse should exist and be owned by current user
docker run --rm --user "${UID}:${GID}" --name some-clickhouse-server --ulimit nofile=262144:262144 -v "$PWD/logs/clickhouse:/var/log/clickhouse-server" -v "$PWD/data/clickhouse:/var/lib/clickhouse" clickhouse/clickhouse-server
```

When you use the image with local directories mounted, you probably want to specify the user to maintain the proper file ownership. Use the `--user` argument and mount `/var/lib/clickhouse` and `/var/log/clickhouse-server` inside the container. Otherwise, the image will complain and not start.

### Start server from root[​](#start-server-from-root "Direct link to Start server from root")

Starting the server from root is useful in cases where user namespace is enabled.
To do so run:

```
docker run --rm -e CLICKHOUSE_RUN_AS_ROOT=1 --name clickhouse-server-userns -v "$PWD/logs/clickhouse:/var/log/clickhouse-server" -v "$PWD/data/clickhouse:/var/lib/clickhouse" clickhouse/clickhouse-server
```

### How to create default database and user on start[​](#how-to-create-default-db-and-user "Direct link to How to create default database and user on start")