Version history

Version history allows you to track and manage different versions of your maps in Builder. CARTO periodically saves versions as you work, and you can also manually save named versions to mark important milestones. This gives you a complete audit trail and the ability to restore previous states.

Accessing version history

To access version history:

1. Open your map in Builder

2. Click the three-dot menu in the top header.

3. Select version history.

The Version History panel will open on the right side of the screen, showing a chronological list of all saved versions.

Version list

The version list displays all versions of your map, with the most recent at the top. Each entry shows:

• Title (for named versions) or "Automatic version" (for auto-saved versions)

• Author who made the changes

• Current version badge for the active version

• Published version badge if the version has been published.

Searching and filtering versions

Use the search bar at the top of the panel to find specific versions by keyword. You can also filter the list using the filter button:

• All: Shows all versions.

• Named versions: Shows only versions with custom titles.

• Published versions: Shows only versions that were published.

Click Show older... at the bottom of the list to load more versions.

Viewing version details

Click on any versions in the list to view its details. The version details popup shows:

• Title and description (if provided)

• Version changes: A summary of what changed in this version compared to the previous one.

The version changes section provides a clear summary of modifications, such as:

• "2 layers were added"

• "1 widget was updated"

• "The basemap was updated"

Saving a named version

While CARTO periodically saves versions automatically, you can manually save a named version to mark important milestones:

1. Click the Save new version button at the top of the Version History panel.

2. Enter a title for this version.

3. Optionally add a description to explain what changed or why this version is significant.

4. Click Save.

Named versions are easier to find later using the search and filter features, and help your team understand the evolution of your map.

Editing version descriptions

You can add or edit descriptions for any version:

1. Click on a version to open its details

2. Click the Edit button (in the top right corner).

3. Update the title or description.

4. Click Save.

Alternatively, hoover over a version in the list and click Edit description or Add description from the context menu.

Restoring a previous version

To restore your map to a previous state:

1. Click on the version you want to restore.

2. Click Restore this version from the version actions menu.

3. A confirmation dialog will appear warning you that unsaved changes to the current version may be lost.

4. Click Yes, restore to confirm.

Restoring a version does not delete other versions. A new version will be created with the restored state, preserving your complete version history.

Previewing versions

When viewing version details, you can see a preview of how the map looked at that point in time. This allows you to compare different versions visually before deciding whether to restore.

The preview shows a static representation of the map layers and styling. Interactive elements like widgets are not included in the preview.

Duplicating a map from a version

You can create a new map based on any historical version:

1. Click on a version in the history.

2. Select Duplicate map from the version actions menu.

3. A new map will be created with the state from that version.

This is useful when you want to create a variation of your map based on a previous state without affecting the current version.

Version history and collaboration

Version history works seamlessly with collaborative maps:

• All collaborators can view the complete version history.

• Changes made by any collaborator are tracked with their name and timestamp.

• This provides a complete audit trail of who made what changes and when.

Version history and publishing

When you publish a map, the published version is marked in the version history with a "Published version" badge. This helps you track which version is currently visible to viewers.