You can install a TimescaleDB instance on any local system, from a pre-built container.
Want to skip these steps?
Deploy a Timescale service in the cloud. We tune your database for performance and handle scalability, high availability, backups and management so you can relax.
This is the simplest method to self-host TimescaleDB, and it means you
always have access to the latest version without worrying about local
dependencies. You can access the Docker image directly from locally installed
PostgreSQL client tools such as psql
If you have already installed PostgreSQL using a method other than the pre-built container provided here, you could encounter errors following these instructions. It is safest to remove any existing PostgreSQL installations before you begin. If you want to keep your current PostgreSQL installation, do not install TimescaleDB using this method. Install from source instead.
Install Docker, if you don't already have it. For packages and instructions, see the Docker installation documentation.
At the command prompt, run the TimescaleDB Docker image:
If your system uses Linux Uncomplicated Firewall (UFW) for security rules, Docker could override your UFW port binding settings. Docker binds the container on Unix-based systems by modifying the Linux IP tables. If you are relying on UFW rules for network security, consider adding DOCKER_OPTS="--iptables=false"
to prevent Docker from overwriting the IP tables. For more information about this vulnerability, see Docker's information about the UFW flaw.
When you have completed the installation, you need to configure your database so
that you can use it. The easiest way to do this is to run the timescaledb-tune
script, which is included with the timescaledb-tools
package. For more
information, see the configuration section.
The TimescaleDB HA Docker image includes Ubuntu as its operating system. The lighter-weight TimescaleDB (non-HA) image uses Alpine. The commands in this section use the TimescaleDB HA image, but the steps are the same for both (except for the location of the data-dir, see below).
You can use the Docker image in different ways, depending on your use case.
If you want to run the image directly from the container, you can use this command:
flag binds the container port to the host port. This means that
anything that can access the host port can also access your TimescaleDB container,
so it's important that you set a PostgreSQL password using the
environment variable. Without that variable, the Docker
container disables password checks for all database users.
If you want to access the container from the host but avoid exposing it to the
outside world, you can bind to 127.0.0.1
instead of the public interface,
using this command:
If you don't want to install psql
and other PostgreSQL client tools locally,
or if you are using a Microsoft Windows host system, you can connect using the
version of psql
that is bundled within the container with this command:
Existing containers can be stopped using docker stop
and started again with
while retaining their volumes and data. When you create a new
container using the docker run
command, by default you also create a new data
volume. When you remove a Docker container with docker rm
the data volume
persists on disk until you explicitly delete it. You can use the docker volume
command to list existing docker volumes. If you want to store the data from
your Docker container in a host directory, or you want to run the Docker image
on top of an existing data directory, you can specify the directory to mount a
data volume using the -v
The two container types store PostgreSQL data dir in different places, make sure you select the correct one to mount:
When you install TimescaleDB using a Docker container, the PostgreSQL settings
are inherited from the container. In most cases, you do not need to adjust them.
However, if you need to change a setting you can add -c setting=value
command. For more information, see the
The link provided in these instructions is for the latest version of TimescaleDB on PostgreSQL 14. To find other Docker tags you can use, see the Dockerhub repository.
When you have PostgreSQL and TimescaleDB installed, you can connect to it from
your local system using the psql
command-line utility. This is the same tool
you might have used to connect to PostgreSQL before, but if you haven't
installed it yet, check out the installing psql section.
If you installed TimescaleDB from the pre-built Docker container, then you probably already have the TimescaleDB extension, and you can skip this procedure.
On your local system, at the command prompt, connect to the PostgreSQL instance as the
superuser:If your connection is successful, you'll see a message like this, followed by the
prompt, create an empty database. Our database is calledexample
:Connect to the database you created:
Add the TimescaleDB extension:
You can now connect to your database using this command:
You can check that the TimescaleDB extension is installed by using the \dx
command at the psql
prompt. It looks like this:
If you have TimescaleDB installed in a Docker container, you can view your logs
using Docker, instead of looking in /var/lib/logs
. For more
information, see the Docker documentation on logs.
Now that you have your first Timescale database up and running, you can check out the Use Timescale section, and find out what you can do with it.
If you want to work through some tutorials to help you get up and running with Timescale and time-series data, check out the tutorials section.
Found an issue on this page?
Report an issue!