Skip to main content
This document describes how to upgrade a self-hosted Teable deployment.

​
Release channels and version tags

The Teable app publishes date-based release tags in the form release.<timestamp>.<build> (for example release.2026-07-14T12-24-39Z.2228), plus two floating channels: Releases ship frequently (often several per week); you decide when to upgrade. All tags are listed on GitHub Packages.
Before performing any upgrade, we strongly recommend backing up your data first.

​
Routine updates: follow the changelog

New features and fixes are announced in the Changelog, and every Teable release tag carries its build date — so “do I have this yet?” is just a date comparison. To pick up something you read about, move your Teable image to any release dated at or after that entry:
  • Docker deployments can simply ride the latest channel:
    Containers are recreated on the new image; your data lives in Docker volumes (or your external database) and is not touched.
  • Kubernetes deployments should not run a floating tag: keep the Teable image pinned and bump the pinned tag deliberately on each update. The deployment repository’s pin-image.sh resolves which concrete release latest currently points to.

​
Best practice: upgrade the whole platform together

A full-featured deployment has two version lines — the Teable app and the platform itself (see Architecture). The most reliable routine ties them together, with VERSIONS.md as the upgrade sheet. On each round:
  1. Upgrade the runtime plane to the newest platform release (v<year>.<month>.<seq>): each git tag is a verified snapshot of every runtime component, and its CHANGELOG.md entry states what changed and what, if anything, you must do (most releases are hot-swappable). Work from the repository checked out at that tag.
  2. Move the Teable app to the concrete release tag that latest currently corresponds to (pin-image.sh resolves it) — a pinned, verified combination instead of a floating channel.
  3. Run the bundled doctor — it checks health and compares what is actually running against the platform release manifest (compatible / upgrade the Teable app / unknown combination).

​
Required secrets

Teable no longer falls back to built-in default secrets. If your deployment relied on those defaults, the first start after upgrading stops with a list of the environment variables it needs and a copy-paste block that preserves your existing sessions, tokens, and encrypted data. Add the block, restart, then plan a rotation. See Secrets and rotation.

​
Database migration

Teable executes database migrations automatically on startup; no manual step is required. If anything looks wrong after an upgrade, check the logs:

​
Rollback

If you hit issues after upgrading:
  1. Set the image tag in docker-compose.yaml back to the previous release tag (this is why pinning beats latest: the previous version is written down).
  2. docker compose up -d
Rolling back after a release that migrated the database schema may not be safe — restore from your pre-upgrade backup in that case. This is the main reason for the backup recommendation above.

​
FAQ

No. Your data is stored in Docker volumes or external databases, and upgrading containers will not affect your data. However, we still recommend backing up before upgrading.
No. Your Instance ID remains unchanged during application updates. It is a permanent identifier for your self-hosted installation.
Typically, pulling new images takes a few minutes (depending on network speed), and container restart only takes a few seconds. The entire process usually completes within 5-10 minutes.
Using docker compose up -d there will be a brief service interruption (usually a few seconds to tens of seconds).
You can check the current version by:
  • Viewing the version number at the bottom left of the Teable interface
  • Using an admin account to access the admin panel
  • Running docker inspect <container> --format='{{.Config.Image}}' to check the image version. If you run the latest channel, the full-featured deployment ships a pin-image.sh helper that resolves which release latest currently is.
  1. First check container logs to troubleshoot: docker compose logs teable
  2. If it’s a database migration issue, try restoring from backup
  3. If the issue persists, rollback to the previous version
  4. Contact support at support@teable.ai
Last modified on August 6, 2026