How To Install TimescaleDB on Ubuntu 20.04
If you’re running a PostgreSQL instance on Ubuntu 20.04 and want to turn it into a time‑series powerhouse, this guide will get you there in under ten minutes – no fluff, just the steps that actually matter.
1 . Make sure PostgreSQL is already installed
TimescaleDB is an extension of PostgreSQL, so you need a working Postgres first. If you’ve never set one up, run:
sudo apt update && sudo apt install postgresql-12
(Replace 12 with your desired version if you’re on something newer.)
Because the Timescale repo will expect a PostgreSQL package in place; otherwise the install script will just hang.
2 . Add the Timescale APT repository
sudo sh -c 'echo "deb https://repo.timescale.com/apt/ubuntu focal main" > /etc/apt/sources.list.d/timescaledb.list'
This line tells apt where to fetch the official packages from.
I once saw a user miss this step and think Timescale is an obscure package that just “appears” in the default Ubuntu repos – they ended up installing an older, incompatible version.
3 . Import the GPG key
wget -qO- https://repo.timescale.com/gpg.key | sudo apt-key add -
The key verifies that the binaries you’re pulling haven’t been tampered with. Skipping it is a security no‑no; your system will refuse to install from an untrusted source.
4 . Update apt and install TimescaleDB
sudo apt update sudo apt install timescaledb-2-postgresql-12
Notice the -2 in the package name – that’s TimescaleDB v2, which is what everyone recommends for new projects. The second part of the suffix must match your PostgreSQL major version; otherwise you’ll end up with a mismatched extension and an error when you try to enable it.
. Configure PostgreSQL to load the extension on start
Open the Timescale config file:
sudo nano /etc/postgresql/12/main/timescaledb.conf
Uncomment or add this line:
timescaledb.telemetry_level = 'off'
The telemetry setting is optional, but turning it off keeps your logs clean and avoids sending data to the Timescale team. Save and exit.
Now edit PostgreSQL’s main config to load the extension automatically:
sudo nano /etc/postgresql/12/main/postgresql.conf
Add at the end of the file:
shared_preload_libraries = 'timescaledb'
This tells PostgreSQL to start TimescaleDB each time it launches. If you forget this, you’ll still be able to use Timescale features by loading the library manually in a session, but you’ll hit the same “extension not found” error every time you restart.
6 . Restart PostgreSQL and verify
sudo systemctl restart postgresql
To confirm everything is wired up:
SELECT * FROM pg_extension WHERE extname = 'timescaledb';
If the query returns a row, congratulations – you’ve got Timescale loaded.
7 . Enable Timescale on a database
Switch to your database and run:
CREATE EXTENSION IF NOT EXISTS timescaledb CASCADE;
This is where the “real world” magic happens: you can now create hypertables, set up retention policies, and use all the fancy time‑series functions that make Timescale worth installing.
8 . (Optional) Test a quick hypertable
CREATE TABLE sensor_data (
time TIMESTAMPTZ NOT NULL,
location TEXT,
temperature DOUBLE PRECISION NULL
);
SELECT create_hypertable('sensor_data', 'time');
Insert some rows and watch the data roll into shards automatically. If you see an error about “invalid input for type timestamptz,” it’s probably because your system clock is out of sync – a classic issue I’ve seen after an overnight reboot on a server that had its NTP service disabled.
9 . Keep Timescale up to date
When new releases drop, just run:
sudo apt update && sudo apt upgrade timescaledb-2-postgresql-12
The same shared_preload_libraries line stays in your config; you don’t need to touch it again.
That’s all there is to it. You now have a PostgreSQL instance that can handle millions of time‑series rows without breaking a sweat. Time to start modeling your data and let the hypertables do the heavy lifting! Enjoy your time‑scaled data adventures!
