Retool stores a version history for every app. To view versions, click the Deploy button dropdown → 'View version history'. Each version is a snapshot of the app at the time it was deployed. Add release notes when deploying to document what changed. To roll back, select a previous version and click 'Restore this version'. Versioning in the free plan has limited history; Business plans have longer retention.
| Fact | Value |
|---|---|
| Tool | Retool |
| Difficulty | Beginner |
| Time required | 15-20 min |
| Compatibility | Retool Cloud and Self-hosted |
| Last updated | March 2026 |
Retool's Built-In Release Versioning System
Every time you deploy a Retool app (click Deploy), Retool creates a new version snapshot of the app's current state. This snapshot is immutable — it captures the queries, components, event handlers, and all configuration at that point in time. Users who access the published app always see the latest deployed version.
Version history lets you roll back to any previous snapshot if a new release introduces a bug or breaks something. It also provides an audit trail of when changes were made and who made them.
This is distinct from Git-based source control (covered in the version control tutorial) — built-in versioning is simpler and doesn't require GitHub integration, but provides less granularity and collaboration features.
Prerequisites
- A Retool app with at least one deployed version
- Editor or Admin access to the app
- Basic understanding of the Retool editor and Deploy button
Step-by-step guide
Create a named version when deploying
When you're ready to deploy changes to your app, click the 'Deploy' button in the top-right of the editor. Instead of immediately deploying, click the dropdown arrow next to Deploy to see 'Deploy with notes'. Enter a version name (e.g., 'v1.2 — Added CSV export button') and optional release notes describing what changed. This makes the version history meaningful for your team. The version name and notes appear in the version history list.
Expected result: App deployed with a named version visible in the version history.
Access the version history
To view all previous versions of an app, click the Deploy button dropdown → 'View version history'. Alternatively, go to the app settings panel (gear icon in the editor) and look for a 'Version history' or 'Releases' section. The version history list shows: version name or number, deployment timestamp, who deployed it, and any release notes. The currently active (live) version is highlighted.
Expected result: Version history list shows all deployed versions with timestamps, deployer, and notes.
Compare two versions
Retool may offer a version comparison view (availability depends on your Retool version) that shows what changed between two releases. If available, select two versions and click 'Compare' to see a diff of query configurations and component properties. If comparison isn't available in your version, use version notes to understand what changed and test manually by previewing each version.
Expected result: Version comparison (if available) shows what changed between releases.
Roll back to a previous version
If a new deployment breaks something, select the previous good version in the version history. Click 'Restore this version' or 'Make this version the current release'. Retool will prompt you to confirm. After confirmation, the selected previous version becomes the live version that all users see. The broken version remains in history — it's not deleted. You can always restore a later version if the rollback itself causes issues.
Expected result: Previous good version is restored and live for all users. Broken version remains in history for reference.
Preview a specific version without affecting live users
You can preview any version in the history without making it live. In the version history, find the version you want to preview and look for a 'Preview' or 'Open in editor' option. This opens the historical snapshot in the editor for your inspection. This is useful for: investigating what a past version looked like, testing whether a rollback would fix an issue before committing, or recovering a query or component that was deleted in a later version.
Expected result: Historical version opens in the Retool editor for inspection without affecting the live app.
Establish a versioning discipline for your team
Decide on a team convention for versioning: when to create a version (every deploy vs only major changes), naming format (semantic versioning vs date-based), and what to include in release notes (changed queries, new features, bug fixes). Document this in your Retool org's internal knowledge base. Consistent versioning practices make rollbacks and incident investigation much faster.
1// Example version naming conventions:2// Option 1: Semantic versioning3// v1.0 — Initial release4// v1.1 — Added status filter5// v1.2 — Fixed CSV export bug6// v2.0 — Redesigned dashboard layout78// Option 2: Date-based9// 2026-01-15 — Q1 reporting features10// 2026-02-01 — Performance optimization11// 2026-03-30 — Security patch1213// Release notes template:14// ADDED: [new features]15// CHANGED: [modified behavior]16// FIXED: [bug fixes]17// REMOVED: [deprecated features]Expected result: Team has a consistent versioning convention that makes the history useful and readable.
Complete working example
1// RETOOL APP RELEASE NOTES TEMPLATE2// Use this format when deploying with notes3// Makes rollbacks and incident investigation much easier45/*6VERSION: v2.37DATE: 2026-03-308DEPLOYED BY: alice@company.com910ADDED:11- Export to CSV button on Orders table (button1 → downloadCSV JS Query)12- Date range filter now defaults to current month13- 'Bulk approve' button for Admin group only1415CHANGED:16- getOrders query now uses server-side pagination (table1.pageIndex)17- Status filter includes new 'on_hold' value from database1819FIXED:20- Fixed null reference error when table1.selectedRow is empty21- Fixed saveChanges not refreshing table after successful update2223QUERIES MODIFIED:24- getOrders: added LIMIT/OFFSET pagination25- updateOrder: added RETURNING * for optimistic locking check26- getOrderStats: enabled caching (TTL: 300s)2728RESOURCES AFFECTED:29- production-postgres: no changes30- order-api: updated timeout from 10s to 30s31*/Common mistakes
Why it's a problem: Deploying without release notes, resulting in a version history that just shows timestamps with no context
How to avoid: Make release notes mandatory in your team's deployment process. Even a one-line description ('Added export button') dramatically improves the usefulness of the version history.
Why it's a problem: Rolling back to a previous version without testing it first in preview mode
How to avoid: Before rolling back a production app, open the target previous version in preview mode and verify it actually resolves the issue. The previous version may have had its own bugs that were fixed in later versions.
Why it's a problem: Confusing Retool's built-in versioning with Git source control and expecting branch-based development workflows
How to avoid: Built-in versioning is linear (a single timeline of releases). For branch-based workflows (feature branches, pull requests, code review), set up Retool's Git sync (Enterprise). Built-in versioning is for release management, not team development workflows.
Best practices
- Always add release notes when deploying — a version history without notes is only marginally useful
- Deploy frequently with small changes rather than infrequently with large changes — smaller releases are easier to roll back
- Test in preview mode before deploying to live — preview mode shows the current editor state without affecting live users
- Keep a changelog document outside Retool for long-term audit purposes — Retool's version history retention may not cover multi-year lookback
- Coordinate deployments on multi-editor apps — deploying over a teammate's in-progress work creates confusion
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I'm using Retool's built-in version history to manage app releases. Help me with: (1) the steps to create a named version when deploying (Deploy button dropdown), (2) how to roll back to v1.3 when v1.4 broke the CSV export, (3) how to preview v1.3 in the editor to verify it works before making it live, (4) a team convention for release notes that includes what queries changed and what bug was fixed. Also explain the difference between this built-in versioning and Retool's Git sync feature.
Access Retool version history: click Deploy button dropdown → 'View version history'. Create version with notes: Deploy → 'Deploy with notes' → enter version name and release notes. Roll back: find previous version in list → 'Restore this version'. Preview old version: 'Open in editor' on historical version. Show the difference between built-in versioning (releases tab) vs Git sync (Enterprise, Settings → Source Control).
Frequently asked questions
How many versions does Retool retain in the version history?
Version history retention depends on your plan. Free and Pro plans have limited version history. Business and Enterprise plans have longer retention. Check your specific retention period in Settings → About or the Retool pricing page. For long-term version archiving beyond Retool's retention, export key versions to Git using Source Control.
Can I see who made specific changes within a version, not just who deployed it?
Retool's built-in versioning records who deployed each version, but not the specific edit-level changes (who edited a specific query or component). For that level of granularity, you need Git sync (Enterprise) which shows individual commits with authors. The audit log records query execution history but not edit-time changes.
Can multiple editors deploy different versions of the same app simultaneously?
No — there is one active (live) version at a time per app. If two editors are working on the same app simultaneously and one deploys, the other's deploy will overwrite it. Coordinate deployments using staging environments and direct team communication.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation