Serialization

Serialization is only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).

Serialization lets you export the contents of one Metabase and import them into another Metabase. It’s useful when you run multiple Metabases, like separate instances for testing and production, or a Metabase per office or region.

  • Export will serialize the contents of your source Metabase as YAML files.
  • Import will read those exported YAML files and create or update those serialized items in the target Metabase.

Serialization format

The Metabase Representation Format repository contains the full specification for the YAML format used by serialization, including schemas for each entity type, examples, and an NPM validation package you can use to validate YAML files.

Serialization use cases

  • Staging environments. Enable a staging-to-production workflow for important dashboards by exporting from a staging instance of Metabase and then importing them into your production instance(s).
  • Version control. Check the exported files into version control and audit changes to them, as the YAML files contained within the export are pretty readable. For a built-in Git workflow with push/pull from the Metabase UI, see Remote Sync.
  • Duplicating assets to other Metabases. Export the “template” data from a source Metabase and import them to one or more target instances.

Check out our guides for:

Importing and exporting your Metabase content

There are two ways to run these export and import commands:

If you’re on Metabase Cloud, the API endpoints are your only option.

How export works

Metabase will only export the following entities:

  • Collections (but personal collections don’t get exported unless you explicitly specify them with the Select collections option)
  • Dashboards
  • Questions (cards)
  • Transforms (including tags and jobs)
  • Documents (without comments)
  • Actions
  • Models
  • Metrics
  • Snippets
  • Data model and table metadata
  • Segments
  • Measures
  • Glossary entries (data definitions)
  • Public sharing settings for questions and dashboards
  • General Metabase settings
  • Events and timelines
  • Notification channels (email and webhook destinations used by alerts and subscriptions)
  • Metabot configuration (AI assistant settings and prompts)
  • Python libraries (shared Python modules used by transforms)
  • Database connection strings (only if specified through the Include database connection details option)

All other entities—including users, groups, permissions, alerts, subscriptions, document comments—won’t get exported. Those entities are tied to user accounts, and therefore aren’t portable between Metabases.

General Metabase settings that are exported

Here’s the list of the general settings Metabase exports in the settings.yaml file. For more on Metabase settings, see Configuring Metabase.

  • aggregated-query-row-limit
  • allowed-iframe-hosts
  • application-colors
  • application-favicon-url
  • application-font
  • application-font-files
  • application-logo-url
  • application-name
  • available-fonts
  • available-locales
  • available-timezones
  • breakout-bins-num
  • csv-field-separator
  • custom-formatting
  • custom-geojson
  • custom-geojson-enabled
  • custom-homepage
  • custom-homepage-dashboard
  • default-maps-enabled
  • disable-cors-on-localhost
  • email-max-recipients-per-second
  • embedded-metabot-enabled?
  • embedding-homepage
  • embedding-hub-production-embed-snippet-created
  • embedding-hub-sso-auth-manual-tested
  • embedding-hub-test-embed-snippet-created
  • enable-embedding
  • enable-nested-queries
  • enable-pivoted-exports
  • enable-sandboxes?
  • enable-whitelabeling?
  • enable-xrays
  • gsheets
  • hide-embed-branding?
  • humanization-strategy
  • landing-page
  • landing-page-illustration
  • landing-page-illustration-custom
  • loading-message
  • login-page-illustration
  • login-page-illustration-custom
  • metabot-chat-system-prompt
  • metabot-enabled?
  • metabot-icon
  • metabot-limit-reset-rate
  • metabot-limit-unit
  • metabot-name
  • metabot-nlq-system-prompt
  • metabot-quota-reached-message
  • metabot-show-illustrations
  • metabot-sql-system-prompt
  • native-query-autocomplete-match-style
  • no-data-illustration
  • no-data-illustration-custom
  • no-object-illustration
  • no-object-illustration-custom
  • non-table-chart-generated
  • persisted-models-enabled
  • report-timezone
  • report-timezone-long
  • report-timezone-short
  • search-typeahead-enabled
  • setup-embedding-autoenabled
  • setup-license-active-at-setup
  • show-homepage-data
  • show-homepage-pin-message
  • show-homepage-xrays
  • show-metabot
  • show-sdk-embed-terms
  • show-simple-embed-terms
  • show-static-embed-terms
  • site-locale
  • site-name
  • source-address-header
  • start-of-week
  • subscription-allowed-domains
  • synchronous-batch-updates
  • system-timezone
  • unaggregated-query-row-limit

How import works

Metabase will read the imported YAML files and look for Entity IDs to figure out which items to create or overwrite. Imports only create or overwrite items; they never delete items from the target instance.

  • If you import an item with an entity_id that doesn’t exist in your target Metabase, Metabase will create a new item.
  • If you import an item with an entity_id that already exists in your target Metabase, the import will overwrite the existing item. In particular, this means that if you export a question, then make a change in an exported YAML file — like rename a question by directly editing the name field — and then import the edited file back, Metabase will try to apply the changes you made to the YAML.
  • If you import an item with a blank entity_id, Metabase will create a new item. Any serdes/meta → id will be ignored in this case.
  • All items and data sources referenced in YAML must either exist in the target Metabase already, or be included in the import. For example, if an exported YAML has the field collection_id: onou5H28Wvy3kWnjxxdKQ, then the collection onou5H28Wvy3kWnjxxdKQ must already exist in the target instance, or there must be a YAML file with the export of a collection that has this ID.

Export options

Export options let you customize what Metabase includes in an export. Every option works with both the API and the CLI — only the syntax differs.

Select collections

  • CLI:-c, --collection <ID[,ID,...]>
  • API:collection=<ID> (repeat to add more)

Type: Integer (comma-separated list for CLI; repeated parameter for API).

Conclusion

Serialization is an important feature for managing Metabase instances across environments. By understanding how to properly export and import data and leveraging the available options, users can effectively manage their data workflow.