Databricks Workspace Export / Import: Practical Guide

When you need to migrate notebooks, folders, and files between Databricks workspaces, take backups, or hand code off to a CI/CD pipeline, the tool you reach for is Workspace Export / Import.

This article walks through the differences between export formats (DBC/SOURCE/HTML), the commands used via Databricks CLI and REST API, how Terraform integration works, and how permissions and secrets are handled during export.

Export Format Comparison

When you export a notebook from a Databricks workspace, you can choose between several formats.

DBC is a Databricks-specific archive (actually a ZIP file under the hood) that lets you export an entire folder in one shot. SOURCE produces plain source code files, which is ideal for storing in a Git repository and reviewing in PRs.

Export / Import via Databricks CLI

Using the Databricks CLI, you can run Export / Import as a batch operation from the command line.

Exporting a single notebook

# SOURCE形式でエクスポート
databricks workspace export \
  /Workspace/Users/[email protected]/etl_pipeline \
  --file ./etl_pipeline.py \
  --format SOURCE

# DBC形式でエクスポート
databricks workspace export \
  /Workspace/Users/[email protected]/etl_pipeline \
  --file ./etl_pipeline.dbc \
  --format DBC

# HTML形式でエクスポート（レポート共有用）
databricks workspace export \
  /Workspace/Users/[email protected]/etl_pipeline \
  --file ./etl_pipeline.html \
  --format HTML

Batch-exporting an entire folder

# フォルダ全体をSOURCE形式で一括エクスポート
databricks workspace export_dir \
  /Workspace/Shared/etl-project \
  ./backup/etl-project \
  --overwrite

Import

# SOURCE形式のインポート
databricks workspace import \
  --path /Workspace/Users/[email protected]/etl_pipeline \
  --file ./etl_pipeline.py \
  --format SOURCE \
  --language PYTHON

# DBC形式の一括インポート
databricks workspace import_dir \
  ./backup/etl-project \
  /Workspace/Shared/etl-project-restored \
  --overwrite

Export / Import via REST API

When you need to run Export / Import programmatically from a CI/CD pipeline, the REST API is the right tool.

# エクスポート（SOURCE形式）
curl -X GET \
  "https://<workspace-url>/api/2.0/workspace/export" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "path": "/Workspace/Users/[email protected]/etl_pipeline",
    "format": "SOURCE"
  }'

# レスポンス（Base64エンコードされたコンテンツ）
{
  "content": "IyBEYXRhYnJpY2tzIG5vdGVib29rIHNvdXJjZQ...",
  "file_type": "py"
}

# インポート（SOURCE形式）
curl -X POST \
  "https://<workspace-url>/api/2.0/workspace/import" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/Workspace/Users/[email protected]/etl_pipeline_v2",
    "format": "SOURCE",
    "language": "PYTHON",
    "content": "IyBEYXRhYnJpY2tzIG5vdGVib29rIHNvdXJjZQ...",
    "overwrite": true
  }'

Note that the REST API content is Base64-encoded. When migrating large numbers of notebooks, the CLI's export_dir/import_dir commands are more efficient.

What's Included and Excluded in Exports

Workspace permissions (ACLs), Secret Scopes, cluster configurations, and job definitions are not exported in any format. To migrate these resources, you need to use the Databricks Terraform Provider or the per-resource APIs in the Databricks CLI individually.

Integration with Terraform

To manage notebook placement in the workspace as IaC, use the Terraform Provider's databricks_notebook resource.

resource "databricks_notebook" "etl_pipeline" {
  path     = "/Workspace/Shared/etl-project/etl_pipeline"
  language = "PYTHON"
  source   = "${path.module}/notebooks/etl_pipeline.py"
}

resource "databricks_notebook" "data_quality" {
  path     = "/Workspace/Shared/etl-project/data_quality"
  language = "SQL"
  source   = "${path.module}/notebooks/data_quality.sql"
}

The benefit of managing this with Terraform is unified management of not just notebook placement, but also clusters, jobs, permissions, Secret Scopes, and other resources. That said, the Terraform apply cycle is heavy for frequent notebook updates. A realistic split is: Repos during the development phase, and DABs or Terraform during the deployment phase.

Workspace Migration Patterns

There are several approaches for migrating notebooks between workspaces.

Best Practices

• Use CLI export_dir + DBC for regular backups: back up workspace notebooks in DBC format on a regular schedule via a cron job or CI/CD schedule.
• Remove hardcoded secrets before migrating: migrate to the Secret Scope approach beforehand so that no secrets end up in the exported code.
• Migrate permissions separately: notebook Export/Import does not carry over permissions, so re-apply them using the Permissions API or Terraform.
• Move to Repos + DABs for the long term: Export/Import is useful for one-off migrations and backups, but Repos + DABs is the better fit for continuous deployment.

Key Points for the Exam

• "How do I migrate notebooks between workspaces?" → Export/Import (DBC format) or Git Clone via Repos
• "Are permissions included in exports?" → No (you must configure them separately via the Permissions API)
• "What's the difference between SOURCE and DBC?" → SOURCE is source code only; DBC is an archive that includes metadata
• "Can HTML exports be imported?" → No (it's a read-only report format)

Test Yourself

Frequently Asked Questions