Run ClickHouse as a service on macOS with standard Homebrew commands.
This tap is a service wrapper only. It ships no ClickHouse binary. It
writes the config files, creates the data and log directories, and provides
brew services integration.
The binary is installed separately. The official installer downloads it into the current directory:
curl https://clickhouse.com/ | shThen move it somewhere on your PATH.
Alternatively, download a stable release build directly:
# Apple silicon
curl -L -o clickhouse https://github.com/ClickHouse/ClickHouse/releases/latest/download/clickhouse-macos-aarch64
# Intel
curl -L -o clickhouse https://github.com/ClickHouse/ClickHouse/releases/latest/download/clickhouse-macos
chmod +x clickhouseThe
clickhousecask is deprecated. It fails the macOS Gatekeeper check and will be disabled on 2026-09-01. Use one of the methods above rather thanbrew install --cask clickhouse.
brew install pavsap/clickhouse/clickhouse-serverEquivalently:
brew tap pavsap/clickhouse
brew install clickhouse-serverHomebrew 6 requires non-official taps to be trusted, otherwise brew upgrade
skips them with a warning:
brew trust pavsap/clickhouseThis is local, per-machine configuration stored in ~/.homebrew/trust.json.
# Basic service control
brew services start|stop|restart clickhouse-server
# Check service status
brew services info clickhouse-server
# Manual start (without a background service)
clickhouse-serverclickhouse-server is a small wrapper installed by this tap. It resolves the
clickhouse binary from your PATH at run time and starts it with this tap's
config. Extra arguments are passed straight through.
# Test local queries
clickhouse client -q 'SELECT 1'
clickhouse client -q 'SELECT version()'
# Test connectivity
curl 'http://localhost:8123/ping'
curl 'http://localhost:8123/?query=SELECT%201'Default configuration files:
/opt/homebrew/etc/clickhouse-server/config.xml/opt/homebrew/etc/clickhouse-server/users.xml
Data directory:
/opt/homebrew/var/lib/clickhouse
Log files, all under /opt/homebrew/var/log/clickhouse-server/:
| File | Written by |
|---|---|
clickhouse-server.log |
ClickHouse itself, per config.xml |
clickhouse-server.err.log |
ClickHouse itself, per config.xml |
clickhouse.log |
the service, capturing stdout |
clickhouse.err.log |
the service, capturing stderr |
If the service fails to start, check clickhouse.err.log first. That is
where the wrapper's own errors land.
| Variable | Effect |
|---|---|
CLICKHOUSE_BINARY |
Use this binary instead of searching PATH |
CLICKHOUSE_CONFIG |
Load this config instead of the tap's config.xml |
Default configuration:
- Empty password for default user
- Access restricted to localhost (127.0.0.1 and ::1)
- Default ports:
- HTTP: 8123
- Native: 9000
- Interserver: 9009
Configuration files are not overwritten on upgrade. To use new configurations:
- Backup existing files
- Remove them
- Reinstall the formula
-
clickhouse binary not found on PATH:The wrapper could not locate a
clickhousebinary. Install one (see Installation above), or point at an existing one:
export CLICKHOUSE_BINARY=/path/to/clickhouse- Permission issues:
sudo chown -R $(whoami) /opt/homebrew/var/lib/clickhouse
sudo chown -R $(whoami) /opt/homebrew/var/log/clickhouse-server- Port conflicts: Edit ports in config.xml and restart the service.
The formula uses a git url with a tag, so it needs no sha256 and a
release is a single atomic step: bump the tag in the formula, then tag that
same commit:
# edit Formula/c/clickhouse-server.rb: tag: "v1.4"
git commit -am "clickhouse-server 1.4"
git tag v1.4
git push origin main v1.4Push the branch and tag together so main never names a tag that is not yet
on the remote.
Do not switch back to an archive/refs/tags/*.tar.gz url. That needs a
sha256 which cannot be computed until the tag exists, which forces a
follow-up commit that the tag itself does not contain.
- Fork the repository
- Create your feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
This project is licensed under the Apache License 2.0. See the LICENSE file for details.