To install ClickHouse on Ubuntu 26.04 or 24.04, add the official APT repository, install the server and client, then start the service with systemd. The same repository setup works on both Ubuntu releases.
ClickHouse is a column-oriented SQL database for analyzing data such as website events, application logs and sales records. This guide sets up a local server, creates a small analytics table and imports a CSV file, then covers updates and removal. If a step fails, leave a comment with the error or contact us.
Before you begin
Ubuntu 26.04 LTS or 24.04 LTS, a sudo account, internet access and a terminal. These steps assume a fresh host installation with systemd, rather than a Docker container.
64-bit amd64 or arm64 hardware. On x86_64, SSE4.2 is an initial check, but current standard builds target x86-64-v3, including AVX2, BMI1/2 and FMA. ARM64 needs NEON and the current build’s additional ARMv8.2-A features; NEON alone does not prove compatibility.
Allow at least 2.5 GB for the binary, plus space for packages, data and logs. For this small practice server, start with 4 GB RAM and two CPU cores as a practical allowance, not a production sizing rule. Real workloads need separate sizing.
Use a new practice database. If ClickHouse is already installed, review its configuration and back up its data before changing repositories or packages.
On x86_64, run the SSE4.2 check, followed by the AVX2 check:
No output from a check means that feature was not found. Stop if AVX2 is missing; SSE4.2 alone is insufficient for current standard builds. These are quick checks, not a complete x86-64-v3 certification. A VM must expose the required features to its guest. On ARM64, skip these x86 checks and verify the processor against the current build requirements.
Expect Ubuntu 26.04 or 24.04 and amd64 or arm64. Stop on another architecture. HTTPS support is already built into modern APT; apt-transport-https is a compatibility package.
Step 2: Save the official signing key
Use a dedicated keyring rather than apt-key. This is the key URL used by the official Debian/Ubuntu instructions, even though its path contains rpm/lts:
On a fresh installation this creates the keyring file. If GPG asks about an existing file, stop and inspect your earlier setup instead of overwriting it without checking.
Step 3: Add the architecture-scoped source
Run both lines in the same terminal. This writes clickhouse.list, so review an existing file before replacing it:
The repository uses stable as its suite, not noble or resolute. The package URL is packages.clickhouse.com/deb, not the ClickHouse homepage. signed-by limits this source to the dedicated keyring. See the official Debian/Ubuntu installation instructions for the upstream reference.
Stable or LTS?
As checked in November 2026, the current branches are 26.10 stable and 26.8 LTS; production teams that prefer LTS can replace stable with lts in the repository line before installing, then run sudo apt update. Stable releases arrive roughly monthly; LTS releases arrive twice a year and receive a year of support, according to the release policy.
The lts channel moves to newer LTS branches over time; it does not pin this machine permanently to 26.8. Do not switch an existing newer stable server to an older LTS as an improvised downgrade.
2. Install, Set a Password and Start the Server
Step 1: Install the server and client
Run the package installation from an interactive terminal:
APT also installs clickhouse-common-static, which contains the main binary. On a fresh interactive installation, ClickHouse asks you to set a password for the default database user. The -y option answers APT prompts; it does not remove the ClickHouse password prompt. Enter a strong, nonempty password and keep it safely.
The installer stores the default user’s password hash in /etc/clickhouse-server/users.d/default-password.xml. This is a database login, separate from your Ubuntu account. Existing authentication settings can change whether the installer asks again.
Keep the server local
If asked whether to allow connections from the network, choose No, the default. With the unmodified configuration, port 9000 serves native TCP and port 8123 serves HTTP on localhost, using 127.0.0.1 and ::1 where available. Do not open firewall ports for this local tutorial.
Choosing Yes can create a network-listening override in config.d/listen.xml. Existing configuration can also change the binding, so verify the actual sockets below. A remote production deployment needs its own user permissions, TLS, network restrictions and backup plan.
Step 2: Enable and start ClickHouse
A fresh package installation does not automatically start the server. Start it now and ensure it is enabled for later boots:
The two checks should report active and enabled. The package may already enable startup; enable --now safely ensures both states. If startup fails, use the log checks in troubleshooting.
Step 3: Verify the listening addresses
Inspect the native and HTTP listeners:
Ubuntu terminal
sudo ss -ltnp '( sport = :9000 or sport = :8123 )'
Expect localhost addresses such as 127.0.0.1:9000 and [::1]:8123. A wildcard such as 0.0.0.0 or [::] means the service is listening beyond localhost; review your config.xml and config.d overrides before continuing.
Step 4: Open the SQL client
Connect as the default database user and enter the password when asked:
Ubuntu terminal
clickhouse-client --password
You should reach a ClickHouse SQL prompt. Do not append your actual password to the command, where it may enter shell history. Inside the client, enter the SQL examples below; run blocks labeled Ubuntu terminal back in your shell.
ClickHouse SQL
SELECT version();
This reports the installed server version. A patched 26.10.x or 26.8.x version is normal for the selected branch; do not pin an old patch just to match a screenshot or example.
3. Create a MergeTree Analytics Table
Use a small website-events dataset. Each row records a page view, its time and a visitor ID. Keep the database name uf_clickhouse_demo for this practice session only; use a different name throughout if it already contains your work.
Step 1: Create the database and table
Run this in the ClickHouse SQL client. Creating the table again returns an error rather than silently reusing an unknown table:
ClickHouse SQL
CREATE DATABASE IF NOT EXISTS uf_clickhouse_demo;
CREATE TABLE uf_clickhouse_demo.page_views
(
event_time DateTime('UTC'),
page LowCardinality(String),
visitor_id UInt64,
duration_seconds UInt32
)
ENGINE = MergeTree
ORDER BY (page, event_time);
DateTime stores the event time in UTC, UInt64 stores a nonnegative visitor ID, and UInt32 stores duration in whole seconds. LowCardinality(String) is useful for a repeated label such as a page path.
MergeTree stores data in parts and merges them in the background. ORDER BY (page, event_time) defines the on-disk sorting key and helps queries filter by page and time; it does not enforce unique rows or guarantee the order of SELECT results. See the MergeTree documentation when designing a larger table.
ClickHouse does not deduplicate these inserts automatically. Repeating the command adds the same four rows again.
Step 3: Summarize visits by page
Run this aggregation in the SQL client:
ClickHouse SQL
SELECT
page,
count() AS views,
uniqExact(visitor_id) AS visitors,
round(avg(duration_seconds), 1) AS avg_seconds
FROM uf_clickhouse_demo.page_views
GROUP BY page
ORDER BY views DESC, page;
count counts views, uniqExact counts distinct visitors, and avg calculates the average visit duration. Before the CSV import, the values should be:
Column-oriented storage lets analytics queries read the columns they need. This query uses three of the table’s four columns and leaves event_time unused. Four rows demonstrate the workflow, not a speed benchmark; evaluate query timing and rows processed with your own larger dataset.
4. Import a CSV File from Your Terminal
Leave the SQL client before running shell commands:
ClickHouse client command
exit
Step 1: Create a CSV in a practice folder
Use a new folder if ~/clickhouse-practice already exists. The following command replaces data.csv in that directory:
The header names match the table columns. Keep dates in the displayed format, page paths as text and the last two columns as nonnegative integers.
Step 2: Stream the file into ClickHouse
Run this from ~/clickhouse-practice in your Ubuntu terminal, and enter your password at the prompt:
Ubuntu terminal
clickhouse-client --password --query="INSERT INTO uf_clickhouse_demo.page_views FORMAT CSVWithNames" < data.csv
The shell reads your local file and the client sends its contents to the server. CSVWithNames reads the header. This avoids server-side file() imports and their /var/lib/clickhouse/user_files path restrictions; do not change server directory permissions just to import a local CSV. Use an interactive terminal so the password prompt has a terminal available.
Step 3: Verify the row count
Count rows after one SQL insert and one CSV import:
Ubuntu terminal
clickhouse-client --password --query="SELECT count() FROM uf_clickhouse_demo.page_views"
Expect 7. No output on a successful INSERT is normal. If the count is higher, a batch may have been imported more than once. Re-run the earlier aggregation in clickhouse-client --password to inspect the combined data.
For the seven-row dataset, /install has 4 views, 3 distinct visitors and an average of 57.5 seconds; /tutorials has 3 views, 3 visitors and an average of 53.3 seconds. Batch files together rather than inserting every event as a separate small request. The client reference covers batch queries and other connection options.
5. Update ClickHouse and Manage the Service
Step 1: Upgrade all three packages together
Before a production update, back up your database using a ClickHouse-aware backup method, test restoration and read the release notes. Schedule a maintenance window, then run:
This updates installed packages within your configured stable or lts channel. Keep server, client and common-static at matching versions; do not upgrade only a hand-picked binary package.
Step 2: Restart and check the running version
Restarting interrupts active connections. After the packages finish upgrading:
SELECT version() checks the running server, not just an installed client executable. Do not copy /var/lib/clickhouse while writes are active and assume that it is a consistent backup.
6. Troubleshoot Installation and Connection Errors
Look for the first useful error: invalid configuration, insufficient memory, unavailable ports or a permissions failure. Review the normal log at /var/log/clickhouse-server/clickhouse-server.log if the error log is empty. Do not fix permissions by making the database directory world-writable.
Issue 2: Connection refused or authentication failed
A refused connection usually means the service is stopped or the host/port is wrong. Authentication failed means the server answered but rejected the credentials. Start with:
Use the database password chosen during installation, not your sudo password. Port 9000 is native TCP; port 8123 is HTTP. If the password is lost, follow a controlled administrator recovery process; do not delete authentication files as a quick fix.
Issue 3: Illegal instruction on startup
An older CPU or a VM that hides required instructions can fail even when its architecture is amd64 or arm64. Return to the CPU checks before reinstalling. Current standard x86 builds need more than the historical SSE4.2 baseline; ARM64 also needs more than a NEON flag. Ubuntu upgrades cannot add missing CPU instructions.
Issue 4: APT or CSV import fails
For an APT signature error, check the key download, signed-by path and conflicting old repository entries. Do not bypass signature verification or use apt-key. For a CSV parse error, inspect the line number, header and field types. A local file error is checked from your shell with:
Ubuntu terminal
pwd
ls -l data.csv
head -n 4 data.csv
Run the stdin import from the folder containing the file. Do not repeat a partly processed import blindly; verify what reached the destination table first.
7. Remove ClickHouse Safely
Step 1: Stop the service and purge all three packages
Back up anything you need first. This stops the database and removes its packages, including the main binary package:
Review APT’s proposed changes before accepting. Do not purge common-static if another ClickHouse component on this host still needs it. Package removal is not a reliable way to erase every database or generated configuration file.
Step 2: Optionally remove the repository and key
Only if you no longer use this repository for any ClickHouse component:
This removes the dedicated source and signing key. It does not delete stored databases.
Step 3: Optionally erase the remaining data
Permanent data loss: after the server is stopped and your backup is verified, use this only if you intend to delete every local ClickHouse database, generated configuration and log in these exact paths:
Do not run this if ClickHouse Keeper or another ClickHouse service shares /var/lib/clickhouse. Custom data paths need separate review. The CSV in ~/clickhouse-practice is your own file and is not removed by these commands.
Helpful Resources
Continue with the official documentation
Official packages lists current stable and LTS patches. The hardware sizing guide helps plan a larger deployment. Local installation is only the first step toward a production database.
Frequently Asked Questions
Can I use the same ClickHouse repository on Ubuntu 26.04 and 24.04?
Yes. The official repository uses stable or lts as its suite, rather than an Ubuntu codename. Select amd64 or arm64 with dpkg and verify that the CPU supports the current standard build.
Is SSE4.2 enough to run current ClickHouse builds?
No. SSE4.2 is an initial compatibility check, but current standard x86 builds target x86-64-v3, which includes AVX2 and other features. ARM64 NEON alone is also insufficient to establish compatibility.
Does apt install -y skip the ClickHouse password prompt?
No. On a fresh interactive installation, the ClickHouse installer still asks for the default database user password. The -y option answers APT prompts. Existing authentication or a noninteractive environment can change installer behavior.
Should I open ports 8123 and 9000?
No firewall opening is needed for this local tutorial. Port 9000 is native TCP and 8123 is HTTP; both use localhost with the default configuration. Remote access needs a separate security configuration.
Why import CSV through clickhouse-client instead of file()?
Standard input lets the client read a file from your user directory and stream it to the server. Server-side file() imports use server filesystem access rules and the configured user_files directory.
Does MergeTree ORDER BY remove duplicate rows?
No. ORDER BY defines the table sorting key. It does not enforce uniqueness, and repeating an INSERT or CSV import can add the same data again.
Does purging ClickHouse delete all my data?
Do not assume so. Remove the server, client and common-static packages, then review remaining data and configuration separately. Deleting /var/lib/clickhouse permanently destroys the databases stored there.