---
title: Install self-hosted TimescaleDB | Tiger Data Docs
description: Install TimescaleDB on Linux, macOS, Windows, Docker, Kubernetes, or from source
---

TimescaleDB is an open-source PostgreSQL extension that powers Tiger Cloud. Designed for running real-time analytics on time-series data, it supercharges ingest, query, storage, and analytics performance.

Note

The following instructions are for development and testing installations. For a production environment, we strongly recommend that you implement the following, many of which you can achieve using PostgreSQL tooling:

- Incremental backup and database snapshots, with efficient point-in-time recovery.
- High availability replication, ideally with nodes across multiple availability zones.
- Automatic failure detection with fast restarts, for both non-replicated and replicated deployments.
- Asynchronous replicas for scaling reads when needed.
- Connection poolers for scaling client connections.
- Zero-down-time minor version and extension upgrades.
- Forking workflows for major version upgrades and other feature testing.
- Monitoring and observability.

* [Linux](#tab-panel-570)
* [macOS](#tab-panel-571)
* [Windows](#tab-panel-572)
* [Docker](#tab-panel-573)
* [Kubernetes](#tab-panel-574)
* [Source](#tab-panel-575)

Install TimescaleDB based on your distribution.

Warning

If you have previously installed PostgreSQL, you may encounter errors following these install instructions. Best practice is to fully remove any existing PostgreSQL installations before you begin. To keep your current PostgreSQL installation, install from source.

- [Debian](#tab-panel-564)
- [Ubuntu](#tab-panel-565)
- [Red Hat](#tab-panel-566)
- [Fedora](#tab-panel-567)
- [RockyLinux](#tab-panel-568)
- [ArchLinux](#tab-panel-569)

1. **Install the latest PostgreSQL packages**

   Terminal window

   ```
   sudo apt install gnupg postgresql-common apt-transport-https lsb-release wget
   ```

2. **Run the PostgreSQL package setup script**

   Terminal window

   ```
   sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
   ```

3. **Add the TimescaleDB package**

   Terminal window

   ```
   echo "deb https://packagecloud.io/timescale/timescaledb/debian/ $(lsb_release -c -s) main" | sudo tee /etc/apt/sources.list.d/timescaledb.list
   ```

4. **Install the TimescaleDB GPG key**

   Terminal window

   ```
   wget --quiet -O - https://packagecloud.io/timescale/timescaledb/gpgkey | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/timescaledb.gpg
   ```

5. **Update your local repository list**

   Terminal window

   ```
   sudo apt update
   ```

6. **Install TimescaleDB**

   Terminal window

   ```
   sudo apt install timescaledb-2-postgresql-18 postgresql-client-18
   ```

   To install a specific TimescaleDB [release](https://packagecloud.io/timescale/timescaledb), set the version. For example:

   `sudo apt-get install timescaledb-2-postgresql-14='2.6.0*' timescaledb-2-loader-postgresql-14='2.6.0*'`

   Older versions of TimescaleDB may not support all the OS versions listed on this page.

7. **Tune your PostgreSQL instance for TimescaleDB**

   Terminal window

   ```
   sudo timescaledb-tune
   ```

   By default, this script is included with the `timescaledb-tools` package when you install TimescaleDB. Use the prompts to tune your development or production environment. For more information on manual configuration, see [Configuration](/docs/reference/configuration/index.md). If you have an issue, run `sudo apt install timescaledb-tools`.

8. **Restart PostgreSQL**

   Terminal window

   ```
   sudo systemctl restart postgresql
   ```

9. **Log in to PostgreSQL as `postgres`**

   Terminal window

   ```
   sudo -u postgres psql
   ```

   You are in the psql shell.

10. **Set the password for `postgres`**

    Terminal window

    ```
    \password postgres
    ```

    When you have set the password, type `\q` to exit psql.

1) **Install the latest PostgreSQL packages**

   Terminal window

   ```
   sudo apt install gnupg postgresql-common apt-transport-https lsb-release wget
   ```

2) **Run the PostgreSQL package setup script**

   Terminal window

   ```
   sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
   ```

3) **Add the TimescaleDB package**

   Terminal window

   ```
   echo "deb https://packagecloud.io/timescale/timescaledb/ubuntu/ $(lsb_release -c -s) main" | sudo tee /etc/apt/sources.list.d/timescaledb.list
   ```

4) **Install the TimescaleDB GPG key**

   Terminal window

   ```
   wget --quiet -O - https://packagecloud.io/timescale/timescaledb/gpgkey | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/timescaledb.gpg
   ```

   For Ubuntu 21.10 and earlier use the following command:

   Terminal window

   ```
   wget --quiet -O - https://packagecloud.io/timescale/timescaledb/gpgkey | sudo apt-key add -
   ```

5) **Update your local repository list**

   Terminal window

   ```
   sudo apt update
   ```

6) **Install TimescaleDB**

   Terminal window

   ```
   sudo apt install timescaledb-2-postgresql-18 postgresql-client-18
   ```

   To install a specific TimescaleDB [release](https://packagecloud.io/timescale/timescaledb), set the version. For example:

   `sudo apt-get install timescaledb-2-postgresql-14='2.6.0*' timescaledb-2-loader-postgresql-14='2.6.0*'`

   Older versions of TimescaleDB may not support all the OS versions listed on this page.

7) **Tune your PostgreSQL instance for TimescaleDB**

   Terminal window

   ```
   sudo timescaledb-tune
   ```

   By default, this script is included with the `timescaledb-tools` package when you install TimescaleDB. Use the prompts to tune your development or production environment. For more information on manual configuration, see [Configuration](/docs/reference/configuration/index.md). If you have an issue, run `sudo apt install timescaledb-tools`.

8) **Restart PostgreSQL**

   Terminal window

   ```
   sudo systemctl restart postgresql
   ```

9) **Log in to PostgreSQL as `postgres`**

   Terminal window

   ```
   sudo -u postgres psql
   ```

   You are in the psql shell.

10) **Set the password for `postgres`**

    Terminal window

    ```
    \password postgres
    ```

    When you have set the password, type `\q` to exit psql.

1. **Install the latest PostgreSQL packages**

   Terminal window

   ```
    sudo yum install https://download.postgresql.org/pub/repos/yum/reporpms/EL-$(rpm -E %{rhel})-x86_64/pgdg-redhat-repo-latest.noarch.rpm
   ```

2. **Add the TimescaleDB repository**

   Terminal window

   ```
   sudo tee /etc/yum.repos.d/timescale_timescaledb.repo <<EOL
   [timescale_timescaledb]
   name=timescale_timescaledb
   baseurl=https://packagecloud.io/timescale/timescaledb/el/$(rpm -E %{rhel})/\$basearch
   repo_gpgcheck=1
   gpgcheck=0
   enabled=1
   gpgkey=https://packagecloud.io/timescale/timescaledb/gpgkey
   sslverify=1
   sslcacert=/etc/pki/tls/certs/ca-bundle.crt
   metadata_expire=300
   EOL
   ```

3. **Update your local repository list**

   Terminal window

   ```
   sudo yum update
   ```

4. **Install TimescaleDB**

   To avoid errors, **do not** install TimescaleDB Apache 2 Edition and TimescaleDB Community Edition at the same time.

   Terminal window

   ```
   sudo yum install timescaledb-2-postgresql-18 postgresql18
   ```

   Note

   On Red Hat Enterprise Linux 8 and later, disable the built-in PostgreSQL module:

   `sudo dnf -qy module disable postgresql`

5. **Initialize the PostgreSQL instance**

   Terminal window

   ```
   sudo /usr/pgsql-18/bin/postgresql-18-setup initdb
   ```

6. **Tune your PostgreSQL instance for TimescaleDB**

   Terminal window

   ```
   sudo timescaledb-tune --pg-config=/usr/pgsql-18/bin/pg_config
   ```

   This script is included with the `timescaledb-tools` package when you install TimescaleDB. For more information, see [configuration](/docs/reference/configuration/index.md).

7. **Enable and start PostgreSQL**

   Terminal window

   ```
   sudo systemctl enable postgresql-18
   sudo systemctl start postgresql-18
   ```

8. **Log in to PostgreSQL as `postgres`**

   Terminal window

   ```
   sudo -u postgres psql
   ```

   You are now in the psql shell.

9. **Set the password for `postgres`**

   Terminal window

   ```
   \password postgres
   ```

   When you have set the password, type `\q` to exit psql.

1) **Install the latest PostgreSQL packages**

   Terminal window

   ```
    sudo yum install https://download.postgresql.org/pub/repos/yum/reporpms/F-$(rpm -E %{fedora})-x86_64/pgdg-fedora-repo-latest.noarch.rpm
   ```

2) **Add the TimescaleDB repository**

   Terminal window

   ```
   sudo tee /etc/yum.repos.d/timescale_timescaledb.repo <<EOL
   [timescale_timescaledb]
   name=timescale_timescaledb
   baseurl=https://packagecloud.io/timescale/timescaledb/el/9/\$basearch
   repo_gpgcheck=1
   gpgcheck=0
   enabled=1
   gpgkey=https://packagecloud.io/timescale/timescaledb/gpgkey
   sslverify=1
   sslcacert=/etc/pki/tls/certs/ca-bundle.crt
   metadata_expire=300
   EOL
   ```

3) **Update your local repository list**

   Terminal window

   ```
   sudo yum update
   ```

4) **Install TimescaleDB**

   To avoid errors, **do not** install TimescaleDB Apache 2 Edition and TimescaleDB Community Edition at the same time.

   Terminal window

   ```
   sudo yum install timescaledb-2-postgresql-18 postgresql18
   ```

   Note

   On Red Hat Enterprise Linux 8 and later, disable the built-in PostgreSQL module:

   `sudo dnf -qy module disable postgresql`

5) **Initialize the PostgreSQL instance**

   Terminal window

   ```
   sudo /usr/pgsql-18/bin/postgresql-18-setup initdb
   ```

6) **Tune your PostgreSQL instance for TimescaleDB**

   Terminal window

   ```
   sudo timescaledb-tune --pg-config=/usr/pgsql-18/bin/pg_config
   ```

   This script is included with the `timescaledb-tools` package when you install TimescaleDB. For more information, see [configuration](/docs/reference/configuration/index.md).

7) **Enable and start PostgreSQL**

   Terminal window

   ```
   sudo systemctl enable postgresql-18
   sudo systemctl start postgresql-18
   ```

8) **Log in to PostgreSQL as `postgres`**

   Terminal window

   ```
   sudo -u postgres psql
   ```

   You are now in the psql shell.

9) **Set the password for `postgres`**

   Terminal window

   ```
   \password postgres
   ```

   When you have set the password, type `\q` to exit psql.

1. **Update your local repository list**

   Terminal window

   ```
   sudo dnf update -y
   sudo dnf install -y epel-release
   ```

2. **Install the latest PostgreSQL packages**

   Terminal window

   ```
    sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
   ```

3. **Add the TimescaleDB repository**

   Terminal window

   ```
   sudo tee /etc/yum.repos.d/timescale_timescaledb.repo <<EOL
   [timescale_timescaledb]
   name=timescale_timescaledb
   baseurl=https://packagecloud.io/timescale/timescaledb/el/9/\$basearch
   repo_gpgcheck=1
   gpgcheck=0
   enabled=1
   gpgkey=https://packagecloud.io/timescale/timescaledb/gpgkey
   sslverify=1
   sslcacert=/etc/pki/tls/certs/ca-bundle.crt
   metadata_expire=300
   EOL
   ```

4. **Disable the built-in {C.PG} module**

   This is for Rocky Linux 9 only.

   Terminal window

   ```
   sudo dnf module disable postgresql -y
   ```

5. **Install TimescaleDB**

   To avoid errors, **do not** install TimescaleDB Apache 2 Edition and TimescaleDB Community Edition at the same time.

   Terminal window

   ```
   sudo dnf install -y postgresql18-server postgresql18-contrib timescaledb-2-postgresql-18
   ```

6. **Initialize the PostgreSQL instance**

   Terminal window

   ```
   sudo /usr/pgsql-18/bin/postgresql-18-setup initdb
   ```

7. **Tune your PostgreSQL instance for TimescaleDB**

   Terminal window

   ```
   sudo timescaledb-tune --pg-config=/usr/pgsql-18/bin/pg_config
   ```

   This script is included with the `timescaledb-tools` package when you install TimescaleDB. For more information, see [configuration](/docs/reference/configuration/index.md).

8. **Enable and start PostgreSQL**

   Terminal window

   ```
   sudo systemctl enable postgresql-18
   sudo systemctl start postgresql-18
   ```

9. **Log in to PostgreSQL as `postgres`**

   Terminal window

   ```
   sudo -u postgres psql
   ```

   You are now in the psql shell.

10. **Set the password for `postgres`**

    Terminal window

    ```
    \password postgres
    ```

    When you have set the password, type `\q` to exit psql.

ArchLinux packages are built by the community.

1. **Install the latest PostgreSQL and TimescaleDB packages**

   Terminal window

   ```
   sudo pacman -Syu timescaledb timescaledb-tune postgresql-libs
   ```

2. **Initalize your PostgreSQL instance**

   Terminal window

   ```
   sudo -u postgres initdb --locale=en_US.UTF-8 --encoding=UTF8 -D /var/lib/postgres/data --data-checksums
   ```

3. **Tune your PostgreSQL instance for TimescaleDB**

   Terminal window

   ```
   sudo timescaledb-tune
   ```

   This script is included with the `timescaledb-tools` package when you install TimescaleDB. For more information, see [configuration](/docs/reference/configuration/index.md).

4. **Enable and start PostgreSQL**

   Terminal window

   ```
   sudo systemctl enable postgresql.service
   sudo systemctl start postgresql.service
   ```

5. **Log in to PostgreSQL as `postgres`**

   Terminal window

   ```
   sudo -u postgres psql
   ```

   You are in the psql shell.

6. **Set the password for `postgres`**

   Terminal window

   ```
    \password postgres
   ```

   When you have set the password, type `\q` to exit psql.

## Add the TimescaleDB extension to your database

For improved performance, you enable TimescaleDB on each database on your self-hosted PostgreSQL instance. This section shows you how to enable TimescaleDB for a new database in PostgreSQL using `psql` from the command line.

1. **Connect to a database on your PostgreSQL instance**

   In PostgreSQL, the default user and database are both `postgres`. To use a different database, set `<database-name>` to the name of that database:

   Terminal window

   ```
   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"
   ```

2. **Add TimescaleDB to the database**

   ```
   CREATE EXTENSION IF NOT EXISTS timescaledb;
   ```

3. **Check that TimescaleDB is installed**

   ```
   \dx
   ```

   You see the list of installed extensions:

   ```
                                                            List of installed extensions
   Name     | Version | Default version |   Schema   |                                      Description
   -------------+---------+-----------------+------------+---------------------------------------------------------------------------------------
   plpgsql     | 1.0     | 1.0             | pg_catalog | PL/pgSQL procedural language
   timescaledb | 2.24.0  | 2.24.0          | public     | Enables scalable inserts and complex queries for time-series data (Community Edition)
   (2 rows)
   ```

   Press `\q` to exit the list of extensions.

You can install TimescaleDB with MacOS and Homebrew.

Warning

If you have already installed PostgreSQL using a method other than Homebrew or MacPorts, you may encounter errors following these install instructions. Best practice is to fully remove any existing PostgreSQL installations before you begin. To keep your current PostgreSQL installation, install from source.

- [Homebrew](#tab-panel-562)
- [MacPorts](#tab-panel-563)

1. **Install Homebrew**

   If homebrew is not already installed on your machine, run the following command:

   Terminal window

   ```
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```

   For more information about Homebrew, including installation instructions, see the [Homebrew documentation](https://docs.brew.sh/Installation).

2. **Install and start PostgreSQL**

   Terminal window

   ```
   brew install postgresql@17
   brew cleanup --prune-prefix
   brew services start postgresql@17
   ```

3. **Add PostgreSQL to your path**

   Terminal window

   ```
    echo 'export PATH="/opt/homebrew/opt/postgresql@17/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc
   ```

4. **Add the TimescaleDB Homebrew tap**

   Terminal window

   ```
   brew tap timescale/tap
   ```

5. **Install TimescaleDB**

   Terminal window

   ```
   brew install timescaledb
   ```

6. **Configure your database**

   Terminal window

   ```
   timescaledb-tune --quiet --yes
   ```

7. **Run the setup script to complete installation**

   Terminal window

   ```
   $(brew --prefix)/Cellar/timescaledb/$(brew list --versions timescaledb | awk '{print $2}')/bin/timescaledb_move.sh
   ```

   This command automatically locates the correct version and runs the setup script.

8. **Start the PostgreSQL service**

   Terminal window

   ```
   brew services restart postgresql@17
   ```

9. **Verify PostgreSQL is running**

   Terminal window

   ```
   brew services list | grep postgresql
   ```

   You should see `postgresql@17` with status `started`.

10. **Connect to PostgreSQL**

    Terminal window

    ```
    psql postgres
    ```

    You are now in the psql shell.

11. **Set the password for your database user**

    (optional but recommended)

    Terminal window

    ```
    \password
    ```

    When you have set the password, type `\q` to exit psql.

1) **Install MacPorts by downloading and running the package installer.**

   For more information about MacPorts, including installation instructions, see the [MacPorts documentation](https://guide.macports.org/#installing.macports).

2) **Install TimescaleDB and psql:**

   Terminal window

   ```
   sudo port install timescaledb libpqxx
   ```

   To view the files installed, run:

   Terminal window

   ```
   port contents timescaledb libpqxx
   ```

   Tips

   MacPorts does not install the `timescaledb-tools` package or run the `timescaledb-tune` script. For more information about tuning your database, see the [TimescaleDB tuning tool](/docs/reference/configuration/index.md).

3) **Log in to PostgreSQL as `postgres`**

   Terminal window

   ```
   sudo -u postgres psql
   ```

   You are in the psql shell.

4) **Set the password for `postgres`**

   Terminal window

   ```
    \password postgres
   ```

   When you have set the password, type `\q` to exit psql.

## Add the TimescaleDB extension to your database

For improved performance, you enable TimescaleDB on each database on your self-hosted PostgreSQL instance. This section shows you how to enable TimescaleDB for a new database in PostgreSQL using `psql` from the command line.

1. **Connect to a database on your PostgreSQL instance**

   In PostgreSQL, the default user and database are both `postgres`. To use a different database, set `<database-name>` to the name of that database:

   Terminal window

   ```
   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"
   ```

2. **Add TimescaleDB to the database**

   ```
   CREATE EXTENSION IF NOT EXISTS timescaledb;
   ```

3. **Check that TimescaleDB is installed**

   ```
   \dx
   ```

   You see the list of installed extensions:

   ```
                                                            List of installed extensions
   Name     | Version | Default version |   Schema   |                                      Description
   -------------+---------+-----------------+------------+---------------------------------------------------------------------------------------
   plpgsql     | 1.0     | 1.0             | pg_catalog | PL/pgSQL procedural language
   timescaledb | 2.24.0  | 2.24.0          | public     | Enables scalable inserts and complex queries for time-series data (Community Edition)
   (2 rows)
   ```

   Press `\q` to exit the list of extensions.

To install TimescaleDB on Windows, you need:

- **OpenSSL v3.x**. For TimescaleDB v2.14.1 only, install OpenSSL v1.1.1.
- **[Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145)**

Warning

If you have previously installed PostgreSQL, you may encounter errors following these install instructions. Best practice is to fully remove any existing PostgreSQL installations before you begin. To keep your current PostgreSQL installation, install from source.

1. **Install the latest version of PostgreSQL and psql**

   1. Download [PostgreSQL](https://www.postgresql.org/download/windows/), then run the installer.

      1. In the `Select Components` dialog, check `Command Line Tools`, along with any other components you want to install, and click `Next`.

      2. Complete the installation wizard.

   2. Check that you can run `pg_config`.

      If you cannot run `pg_config` from the command line, in the Windows Search tool, enter `system environment variables`. The path should be `C:\Program Files\PostgreSQL\<version>\bin`.

2. **Install TimescaleDB**

   1. Unzip the [installer](/docs/get-started/choose-your-path/install-timescaledb#windows-downloads/index.md) to `<install_dir>`, that is, your selected directory.

      Best practice is to use the latest version.

   2. In `<install_dir>\timescaledb`, right-click `setup.exe`, then choose `Run as Administrator`.

   3. Complete the installation wizard.

      During installation, the wizard will prompt you to run the `timescaledb-tune` script to optimize your PostgreSQL configuration. It is recommended to accept this option. For more information, see [configuration](/docs/reference/configuration/index.md).

      If you see an error like `could not load library "C:/Program Files/PostgreSQL/17/lib/timescaledb-2.17.2.dll": The specified module could not be found.`, use [Dependencies](https://github.com/lucasg/Dependencies) to ensure that your system can find the compatible DLLs for this release of TimescaleDB.

3. **Restart the PostgreSQL service**

   Terminal window

   ```
   Restart-Service postgresql-x64-18
   ```

   Replace `18` with your PostgreSQL version if different.

## Add the TimescaleDB extension to your database

For improved performance, you enable TimescaleDB on each database on your self-hosted PostgreSQL instance. This section shows you how to enable TimescaleDB for a new database in PostgreSQL using `psql` from the command line.

1. **Connect to a database on your PostgreSQL instance**

   In PostgreSQL, the default user and database are both `postgres`. To use a different database, set `<database-name>` to the name of that database:

   Terminal window

   ```
   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"
   ```

2. **Add TimescaleDB to the database**

   ```
   CREATE EXTENSION IF NOT EXISTS timescaledb;
   ```

3. **Check that TimescaleDB is installed**

   ```
   \dx
   ```

   You see the list of installed extensions:

   ```
                                                            List of installed extensions
   Name     | Version | Default version |   Schema   |                                      Description
   -------------+---------+-----------------+------------+---------------------------------------------------------------------------------------
   plpgsql     | 1.0     | 1.0             | pg_catalog | PL/pgSQL procedural language
   timescaledb | 2.24.0  | 2.24.0          | public     | Enables scalable inserts and complex queries for time-series data (Community Edition)
   (2 rows)
   ```

   Press `\q` to exit the list of extensions.

## Windows downloads

The latest TimescaleDB releases for PostgreSQL:

- [PostgreSQL 18](https://github.com/timescale/timescaledb/releases/download/2.26.2/TimescaleDB.Windows.PG18.zip)
- [PostgreSQL 17](https://github.com/timescale/timescaledb/releases/download/2.26.2/TimescaleDB.Windows.PG17.zip)
- [PostgreSQL 16](https://github.com/timescale/timescaledb/releases/download/2.26.2/TimescaleDB.Windows.PG16.zip)
- [PostgreSQL 15](https://github.com/timescale/timescaledb/releases/download/2.26.2/TimescaleDB.Windows.PG15.zip)

For release information, see the [GitHub releases page](https://github.com/timescale/timescaledb/releases).

You can install a TimescaleDB instance on any local system from a pre-built Docker container.

To install TimescaleDB from Docker, you need:

- **[Docker](https://docs.docker.com/get-started/get-docker/)**
- **[psql](/docs/integrate/query-administration/psql/index.md)**

* [TimescaleDB-HA](#tab-panel-560)
* [TimescaleDB light](#tab-panel-561)

1. **Run the TimescaleDB Docker image**

   The [TimescaleDB HA](https://hub.docker.com/r/timescale/timescaledb-ha) Docker image offers the most complete TimescaleDB experience. It uses [Ubuntu](https://ubuntu.com), includes [TimescaleDB Toolkit](https://github.com/timescale/timescaledb-toolkit), and support for PostGIS and Patroni.

   To install the latest release based on PostgreSQL 18:

   ```
   docker pull timescale/timescaledb-ha:pg18
   ```

   TimescaleDB is pre-created in the default PostgreSQL database and is added by default to any new database you create in this image.

2. **Run the container**

   Replace `</a/local/data/folder>` with the path to the folder you want to keep your data in the following command.

   ```
   docker run -d --name timescaledb -p 5432:5432  -v </a/local/data/folder>:/pgdata -e PGDATA=/pgdata -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg18
   ```

   If you are running multiple container instances, change the port each Docker instance runs on.

   Note

   If you have a local PostgreSQL instance already running on port 5432, change the Docker port mapping to avoid conflicts. For example, use `-p 5433:5432` and adjust the connection string accordingly.

   On UNIX-based systems, Docker modifies Linux IP tables to bind the container. If your system uses Linux Uncomplicated Firewall (UFW), Docker may [override your UFW port binding settings](https://www.techrepublic.com/article/how-to-fix-the-docker-and-ufw-security-flaw/). To prevent this, add `DOCKER_OPTS="--iptables=false"` to `/etc/default/docker`.

3. **Connect to a database on your PostgreSQL instance**

   The default user and database are both `postgres`. You set the password in `POSTGRES_PASSWORD` in the previous step. The default command to connect to PostgreSQL is:

   Terminal window

   ```
   psql -d "postgres://postgres:password@127.0.0.1:5432/postgres"
   ```

   If you changed the port mapping in step 2 (e.g., to 5433), update the port in the connection string accordingly.

4. **Check that TimescaleDB is installed**

   ```
   \dx
   ```

   You see the list of installed extensions:

   ```
           Name         | Version | Default version |   Schema   |                                      Description
   ---------------------+---------+-----------------+------------+---------------------------------------------------------------------------------------
    plpgsql             | 1.0     | 1.0             | pg_catalog | PL/pgSQL procedural language
    timescaledb         | 2.24.0  | 2.24.0          | public     | Enables scalable inserts and complex queries for time-series data (Community Edition)
    timescaledb_toolkit | 1.22.0  | 1.22.0          | public     | Library of analytical hyperfunctions, time-series pipelining, and other SQL utilities
   (3 rows)
   ```

   Press `q` to exit the list of extensions.

## More Docker options

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:

Terminal window

```
docker run -d --name timescaledb -p 127.0.0.1:5432:5432 \
-v </a/local/data/folder>:/pgdata -e PGDATA=/pgdata -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg18
```

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:

Terminal window

```
docker exec -it timescaledb psql -U postgres
```

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` to your Docker `run` command. For more information, see the [Docker documentation](https://hub.docker.com/_/postgres).

The link provided in these instructions is for the latest version of TimescaleDB on PostgreSQL 18. To find other Docker tags you can use, see the [Dockerhub repository](https://hub.docker.com/r/timescale/timescaledb/tags?page=1\&ordering=last_updated).

## View logs in Docker

If you have TimescaleDB installed in a Docker container, you can view your logs using Docker, instead of looking in `/var/lib/logs` or `/var/logs`. For more information, see the [Docker documentation on logs](https://docs.docker.com/engine/logging/).

1. **Run the TimescaleDB Docker image**

   The light-weight [TimescaleDB](https://hub.docker.com/r/timescale/timescaledb) Docker image uses [Alpine](https://alpinelinux.org/) and does not contain [TimescaleDB Toolkit](https://github.com/timescale/timescaledb-toolkit) or support for PostGIS and Patroni.

   To install the latest release based on PostgreSQL 18:

   ```
   docker pull timescale/timescaledb:latest-pg18
   ```

   TimescaleDB is pre-created in the default PostgreSQL database and added by default to any new database you create in this image.

2. **Run the container**

   ```
   docker run -v </a/local/data/folder>:/pgdata -e PGDATA=/pgdata \
       -d --name timescaledb -p 5432:5432 -e POSTGRES_PASSWORD=password timescale/timescaledb:latest-pg18
   ```

   If you are running multiple container instances, change the port each Docker instance runs on.

   Note

   If you have a local PostgreSQL instance already running on port 5432, change the Docker port mapping to avoid conflicts. For example, use `-p 5433:5432` and adjust the connection string accordingly.

   On UNIX-based systems, Docker modifies Linux IP tables to bind the container. If your system uses Linux Uncomplicated Firewall (UFW), Docker may [override your UFW port binding settings](https://www.techrepublic.com/article/how-to-fix-the-docker-and-ufw-security-flaw/). To prevent this, add `DOCKER_OPTS="--iptables=false"` to `/etc/default/docker`.

3. **Connect to a database on your PostgreSQL instance**

   The default user and database are both `postgres`. You set the password in `POSTGRES_PASSWORD` in the previous step. The default command to connect to PostgreSQL in this image is:

   Terminal window

   ```
   psql -d "postgres://postgres:password@127.0.0.1:5432/postgres"
   ```

   If you changed the port mapping in step 2 (e.g., to 5433), update the port in the connection string accordingly.

4. **Check that TimescaleDB is installed**

   ```
   \dx
   ```

   You see the list of installed extensions:

   ```
                                                            List of installed extensionsh
       Name     | Version | Default version |   Schema   |                                      Description
   -------------+---------+-----------------+------------+---------------------------------------------------------------------------------------
    plpgsql     | 1.0     | 1.0             | pg_catalog | PL/pgSQL procedural language
    timescaledb | 2.24.0  | 2.24.0          | public     | Enables scalable inserts and complex queries for time-series data (Community Edition)
   ```

   Press `q` to exit the list of extensions.

   ## More Docker options

   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:

   Terminal window

   ```
   docker run -v </a/local/data/folder>:/pgdata -e PGDATA=/pgdata \
   -d --name timescaledb -p 127.0.0.1:5432:5432 \
   -e POSTGRES_PASSWORD=password timescale/timescaledb:latest-pg18
   ```

   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:

   Terminal window

   ```
   docker exec -it timescaledb psql -U postgres
   ```

   Existing containers can be stopped using `docker stop` and started again with `docker start` 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 ls` 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` flag:

   Terminal window

   ```
   docker run -d --name timescaledb -p 5432:5432 \
   -v </your/data/dir>:/pgdata -e PGDATA=/pgdata \
   -e POSTGRES_PASSWORD=password timescale/timescaledb:latest-pg18
   ```

   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` to your Docker `run` command. For more information, see the [Docker documentation](https://hub.docker.com/_/postgres).

   The link provided in these instructions is for the latest version of TimescaleDB on PostgreSQL 18. To find other Docker tags you can use, see the [Dockerhub repository](https://hub.docker.com/r/timescale/timescaledb/tags?page=1\&ordering=last_updated).

   ## View logs in Docker

   If you have TimescaleDB installed in a Docker container, you can view your logs using Docker, instead of looking in `/var/log`. For more information, see the [Docker documentation on logs](https://docs.docker.com/engine/logging/).

You can run TimescaleDB inside Kubernetes using the TimescaleDB Docker container images.

To run TimescaleDB inside Kubernetes, you need:

- **[Self-managed Kubernetes](https://kubernetes.io/docs/setup/) or a Kubernetes [Turnkey Cloud Solution](https://kubernetes.io/docs/setup/production-environment/turnkey-solutions/)**.
- **[kubectl](https://kubernetes.io/docs/tasks/tools/)** for command-line interaction with your cluster.

## Integrate TimescaleDB in a Kubernetes cluster

Running TimescaleDB on Kubernetes is similar to running PostgreSQL. This procedure outlines the steps for a non-distributed system.

To connect your Kubernetes cluster to self-hosted TimescaleDB running in the cluster:

1. **Create a default namespace for Tiger Data components**

   1. Create the Tiger Data namespace:

      Terminal window

      ```
      kubectl create namespace tigerdata
      ```

   2. Set this namespace as the default for your session:

      Terminal window

      ```
      kubectl config set-context --current --namespace=tigerdata
      ```

   For more information, see [Kubernetes Namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).

2. **Set up a persistent volume claim (PVC) storage**

   To manually set up a persistent volume and claim for self-hosted Kubernetes, run the following command:

   ```
   kubectl apply -f - <<EOF
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: tigerdata-pvc
   spec:
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         storage: 10Gi
   EOF
   ```

3. **Deploy TimescaleDB as a StatefulSet**

   By default, the [TimescaleDB HA Docker image](https://hub.docker.com/r/timescale/timescaledb-ha/tags) you are installing on Kubernetes uses the default PostgreSQL database, user and password. This image includes TimescaleDB and TimescaleDB Toolkit. To deploy TimescaleDB on Kubernetes, run the following command:

   ```
   kubectl apply -f - <<EOF
   apiVersion: apps/v1
   kind: StatefulSet
   metadata:
     name: timescaledb
   spec:
     serviceName: timescaledb
     replicas: 1
     selector:
       matchLabels:
         app: timescaledb
     template:
       metadata:
         labels:
           app: timescaledb
       spec:
         containers:
           - name: timescaledb
             image: 'timescale/timescaledb-ha:pg18'
             env:
               - name: POSTGRES_USER
                 value: postgres
               - name: POSTGRES_PASSWORD
                 value: postgres
               - name: POSTGRES_DB
                 value: postgres
               - name: PGDATA
                 value: /var/lib/postgresql/data/pgdata
             ports:
               - containerPort: 5432
             volumeMounts:
               - mountPath: /var/lib/postgresql/data
                 name: tigerdata-storage
         volumes:
           - name: tigerdata-storage
             persistentVolumeClaim:
               claimName: tigerdata-pvc
   EOF
   ```

4. **Allow applications to connect by exposing TimescaleDB within Kubernetes**

   ```
   kubectl apply -f - <<EOF
   apiVersion: v1
   kind: Service
   metadata:
    name: timescaledb
   spec:
    selector:
      app: timescaledb
    ports:
      - protocol: TCP
        port: 5432
        targetPort: 5432
    type: ClusterIP
   EOF
   ```

5. **Create a Kubernetes secret to store the database credentials**

   Terminal window

   ```
   kubectl create secret generic tigerdata-secret \
   --from-literal=PGHOST=timescaledb \
   --from-literal=PGPORT=5432 \
   --from-literal=PGDATABASE=postgres \
   --from-literal=PGUSER=postgres \
   --from-literal=PGPASSWORD=postgres
   ```

6. **Deploy an application that connects to TimescaleDB**

   Terminal window

   ```
      kubectl apply -f - <<EOF
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: tigerdata-app
      spec:
        replicas: 1
        selector:
          matchLabels:
            app: tigerdata-app
        template:
          metadata:
            labels:
              app: tigerdata-app
          spec:
            containers:
            - name: tigerdata-container
              image: postgres:latest
              envFrom:
                - secretRef:
                    name: tigerdata-secret
      EOF
   ```

7. **Test the database connection**

   1. Create and run a pod to verify database connectivity using your [connection details](/docs/integrate/find-connection-details/index.md) saved in `tigerdata-secret`:

      Terminal window

      ```
      kubectl run test-pod --image=postgres --restart=Never \
      --env="PGHOST=$(kubectl get secret tigerdata-secret -o=jsonpath='{.data.PGHOST}' | base64 --decode)" \
      --env="PGPORT=$(kubectl get secret tigerdata-secret -o=jsonpath='{.data.PGPORT}' | base64 --decode)" \
      --env="PGDATABASE=$(kubectl get secret tigerdata-secret -o=jsonpath='{.data.PGDATABASE}' | base64 --decode)" \
      --env="PGUSER=$(kubectl get secret tigerdata-secret -o=jsonpath='{.data.PGUSER}' | base64 --decode)" \
      --env="PGPASSWORD=$(kubectl get secret tigerdata-secret -o=jsonpath='{.data.PGPASSWORD}' | base64 --decode)" \
      -- sleep infinity
      ```

   2. Launch the PostgreSQL interactive shell within the created `test-pod`:

      Terminal window

      ```
      kubectl exec -it test-pod -- bash -c "psql -h \$PGHOST -U \$PGUSER -d \$PGDATABASE"
      ```

   You see the PostgreSQL interactive terminal.

## Install with PostgreSQL Kubernetes operators

You can also use PostgreSQL Kubernetes operators to simplify installation, configuration, and life cycle management:

- [StackGres](https://github.com/ongres/stackgres) (includes TimescaleDB images)
- [PostgreSQL Operator (Patroni)](https://github.com/zalando/postgres-operator)
- [PGO](https://github.com/CrunchyData/postgres-operator)
- [CloudNativePG](https://github.com/cloudnative-pg/cloudnative-pg)

You can install TimescaleDB on any local system from source.

To install TimescaleDB from source, you need:

- **PostgreSQL**: Install a [supported version of PostgreSQL](https://www.postgresql.org/download/). We recommend not using TimescaleDB with PostgreSQL 17.1, 16.5, 15.9, 14.14, 13.17, or 12.21. These minor versions [introduced a breaking binary interface change](https://www.postgresql.org/about/news/postgresql-172-166-1510-1415-1318-and-1222-released-2965/) that was reverted in subsequent releases. Build with PostgreSQL 17.2, 16.6, or higher.

- **Build tools**:

  - [CMake 3.11 or later](https://cmake.org/download/)
  - C language compiler (`gcc` or `clang`). On Windows, Visual Studio 2015 or later works instead, ensure you install the CMake and Git components.

1. **Install the latest PostgreSQL source**

   1. At the command prompt, clone the TimescaleDB GitHub repository:

      Terminal window

      ```
      git clone https://github.com/timescale/timescaledb
      ```

   2. Change into the cloned directory:

      Terminal window

      ```
      cd timescaledb
      ```

   3. Checkout the latest release. You can find the latest release tag on our [Releases page](https://github.com/timescale/timescaledb/releases):

      Terminal window

      ```
      git checkout <latest-version>
      ```

      This command produces an error that you are now in `detached head` state. It is expected behavior, and it occurs because you have checked out a tag, and not a branch. Continue with the steps in this procedure as normal.

2. **Build the source**

   1. Bootstrap the build system:

      - [Linux](#tab-panel-549)
      - [Windows](#tab-panel-550)

      Terminal window

      ```
      ./bootstrap
      ```

      Terminal window

      ```
      bootstrap.bat
      ```

      For installation on Microsoft Windows, you might need to add the `pg_config` and `cmake` file locations to your path. In the Windows Search tool, search for `system environment variables`. The path for `pg_config` should be `C:\Program Files\{C.PG}\<version>\bin`. The path for `cmake` is within the Visual Studio directory.

   2. Build the extension:

      - [Linux](#tab-panel-551)
      - [Windows](#tab-panel-552)

      Terminal window

      ```
      cd build && make
      ```

      Terminal window

      ```
      cmake --build ./build --config Release
      ```

3. **Install TimescaleDB**

   - [Linux](#tab-panel-553)
   - [Windows](#tab-panel-554)

   Terminal window

   ```
   make install
   ```

   Terminal window

   ```
   cmake --build ./build --config Release --target install
   ```

4. **Configure PostgreSQL**

   If you have more than one version of PostgreSQL installed, TimescaleDB can only be associated with one of them. The TimescaleDB build scripts use `pg_config` to find out where PostgreSQL stores its extension files, so you can use `pg_config` to find out which PostgreSQL installation TimescaleDB is using.

   1. Locate the `postgresql.conf` configuration file:

      Terminal window

      ```
      psql -d postgres -c "SHOW config_file;"
      ```

   2. Open the `postgresql.conf` file and update `shared_preload_libraries` to:

      Terminal window

      ```
      shared_preload_libraries = 'timescaledb'
      ```

      If you use other preloaded libraries, make sure they are comma separated.

   3. Tune your PostgreSQL instance for TimescaleDB

      Terminal window

      ```
      sudo timescaledb-tune
      ```

      This script is included with the `timescaledb-tools` package when you install TimescaleDB. For more information, see [configuration](/docs/reference/configuration/index.md).

   4. Restart the PostgreSQL instance:

      - [Linux](#tab-panel-555)
      - [Windows](#tab-panel-556)

      Terminal window

      ```
      service postgresql restart
      ```

      Terminal window

      ```
      pg_ctl restart
      ```

5. **Set the user password**

   1. Log in to PostgreSQL as `postgres`

      Terminal window

      ```
      sudo -u postgres psql
      ```

      You are in the psql shell.

   2. Set the password for `postgres`

      Terminal window

      ```
      \password postgres
      ```

      When you have set the password, type `\q` to exit psql.

## Add the TimescaleDB extension to your database

For improved performance, you enable TimescaleDB on each database on your self-hosted PostgreSQL instance. This section shows you how to enable TimescaleDB for a new database in PostgreSQL using `psql` from the command line.

1. **Connect to a database on your PostgreSQL instance**

   In PostgreSQL, the default user and database are both `postgres`. To use a different database, set `<database-name>` to the name of that database:

   Terminal window

   ```
   psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"
   ```

2. **Add TimescaleDB to the database**

   ```
   CREATE EXTENSION IF NOT EXISTS timescaledb;
   ```

3. **Check that TimescaleDB is installed**

   ```
   \dx
   ```

   You see the list of installed extensions:

   ```
                                                            List of installed extensions
   Name     | Version | Default version |   Schema   |                                      Description
   -------------+---------+-----------------+------------+---------------------------------------------------------------------------------------
   plpgsql     | 1.0     | 1.0             | pg_catalog | PL/pgSQL procedural language
   timescaledb | 2.24.0  | 2.24.0          | public     | Enables scalable inserts and complex queries for time-series data (Community Edition)
   (2 rows)
   ```

   Press `\q` to exit the list of extensions.

## Supported platforms

- [Linux](#tab-panel-557)
- [macOS](#tab-panel-558)
- [Windows](#tab-panel-559)

| Operation system                | Version                                                                                                   |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Debian                          | 13 Trixe, 12 Bookworm, 11 Bullseye                                                                        |
| Ubuntu                          | 24.04 Noble Numbat, 22.04 LTS Jammy Jellyfish                                                             |
| Red Hat Enterprise              | Linux 9, Linux 8                                                                                          |
| Fedora                          | Fedora 35, Fedora 34, Fedora 33                                                                           |
| Rocky Linux                     | Rocky Linux 9 (x86\_64), Rocky Linux 8                                                                    |
| ArchLinux (community-supported) | Check the [available packages](https://archlinux.org/packages/?sort=\&q=timescale\&maintainer=\&flagged=) |

| Operation system | Version                          |
| ---------------- | -------------------------------- |
| macOS            | From 10.15 Catalina to 14 Sonoma |

You can deploy TimescaleDB on the following systems:

| Operation system         | Version          |
| ------------------------ | ---------------- |
| Microsoft Windows        | 10, 11           |
| Microsoft Windows Server | 2019, 2022, 2025 |