Skip to main content
Windows usersClickHouse runs natively on Linux and macOS. On Windows, run these steps inside the Windows Subsystem for Linux (WSL).
The ClickHouse CLI (clickhousectl, alias chctl) installs and manages local ClickHouse versions, runs local ClickHouse and Postgres servers, runs queries, and manages ClickHouse Cloud. This page walks you through installing the CLI, starting a local ClickHouse server, and connecting to it. If you used the quick install script, clickhousectl is already installed. Skip to Install ClickHouse.
1

Install the ClickHouse CLI

The install script supports macOS and Linux on x86_64 and ARM64:
The script installs clickhousectl to ~/.local/bin and creates a chctl alias next to it. If the script says ~/.local/bin is not on your PATH, add it, and add the same line to your shell profile (~/.bashrc, ~/.zshrc) for future sessions:
Only the install script and npm create the chctl alias.
To check for a newer CLI release, and to install it:
2

Install ClickHouse

Install the latest version of ClickHouse and make it your default:
local use installs the version if it isn’t already present, sets it as your default, and creates a clickhouse symlink in ~/.local/bin, so you can run the clickhouse binary directly. Any later step in these docs that runs a clickhouse command then works as-is, provided ~/.local/bin is on your PATH.You can also select the latest long-term support release, or a specific version:
To see which minor versions are available to download, and which versions you have installed:
Use vs installclickhousectl local use <version> installs a version and makes it your default, updating the clickhouse symlink. clickhousectl local install <version> only downloads a version; it becomes your default only if you have no default yet, and it doesn’t update the symlink. To set the default without creating or updating the symlink, use clickhousectl local use <version> --no-global.
3

Start clickhouse-server

clickhousectl scopes local servers to the directory you run it from. Create a project directory and start a server there:
The server runs in the background and is named default. Its data lives in ./.clickhouse/, so run later clickhousectl local commands from the same directory; clickhousectl doesn’t search parent directories. The server listens on HTTP port 8123 and TCP port 9000, or on free ports when those are taken. To choose the ports, pass --http-port and --tcp-port. To run more than one server, give each a name, such as clickhousectl local server start dev.To verify it’s running:
4

Start clickhouse-client

Connect to the server with clickhouse-client, from the same directory:
local client connects to the server named default and uses the same ClickHouse version as the server. Pass a name to connect to another server, such as clickhousectl local client dev. You will see something like this:
You’re now ready to start sending SQL commands to ClickHouse! Type exit to leave the client.To run a single query without opening an interactive session, pass -q:
Creating tables in ClickHouse walks you through creating tables and inserting data.
5

Stop the server

The server keeps running in the background until you stop it. Stop it from the same directory:
Stopping preserves the server’s data for the next clickhousectl local server start.
clickhousectl local server remove permanently deletes a stopped server’s data.

​
Next steps

  • Run Postgres locally. With Docker running, start a local Postgres server and connect to it with psql:
  • Connect to ClickHouse Cloud. Create an account, or log in to an existing one. Browser login is read-only; creating or changing Cloud resources needs an API key, which clickhousectl cloud auth login --interactive prompts for.
  • Learn the rest of the CLI. See the clickhousectl reference, or run clickhousectl --help.