# Serialization

Serialization is only available on [Pro](/content/product/pro/index.html) and [Enterprise](/content/product/enterprise/index.html) 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](https://github.com/metabase/representations) repository contains the full specification for the YAML format used by serialization, including schemas for each entity type, examples, and an [NPM validation package](https://www.npmjs.com/package/@metabase/representations) 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](/content/docs/latest/installation-and-operation/remote-sync/index.html).
- **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:

- [Running multiple environments](/content/learn/metabase-basics/administration/administration-and-operation/multi-env/index.html)
- [Setting up git-based workflow](/content/learn/metabase-basics/administration/administration-and-operation/git-based-workflow/index.html)

## Importing and exporting your Metabase content

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

- [Using CLI commands](/content/docs/latest/installation-and-operation/serialization#serialization-with-cli-commands/index.html)
- [Through the API](/content/docs/latest/installation-and-operation/serialization#serialization-via-the-api/index.html)

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](/content/docs/latest/installation-and-operation/serialization#select-collections/index.html) 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](/content/docs/latest/installation-and-operation/serialization#general-metabase-settings-that-are-exported/index.html)
- 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](/content/docs/latest/installation-and-operation/serialization#include-database-connection-details/index.html) 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](/content/docs/latest/configuring-metabase/start/index.html).

- 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](/content/docs/latest/installation-and-operation/serialization#metabase-uses-entity-ids-to-identify-metabase-items/index.html) 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`](/content/docs/latest/installation-and-operation/serialization#metabase-uses-entity-ids-to-identify-metabase-items/index.html) 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](/content/docs/latest/installation-and-operation/serialization#serialization-via-the-api/index.html) and the [CLI](/content/docs/latest/installation-and-operation/serialization#serialization-with-cli-commands/index.html) — 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.