# Metabase Migration Toolkit
[](https://github.com/YOUR_USERNAME/metabase-migration-toolkit/actions/workflows/tests.yml)
[](https://codecov.io/gh/YOUR_USERNAME/metabase-migration-toolkit)
[](https://badge.fury.io/py/metabase-migration-toolkit)
[](https://pypi.org/project/metabase-migration-toolkit/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
This toolkit provides two command-line tools, `metabase-export` and `metabase-import`, designed for exporting and importing Metabase content (collections, questions, and dashboards) between instances.
It's built to be robust, handling API rate limits, pagination, and providing clear logging and error handling for production use.
## Features
- **Recursive Export:** Traverses the entire collection tree, preserving hierarchy.
- **Selective Content:** Choose to include dashboards and archived items.
- **Permissions Migration:** Export and import permission groups and access control settings (NEW!).
- **Database Remapping:** Intelligently remaps questions and cards to new database IDs on the target instance.
- **Conflict Resolution:** Strategies for handling items that already exist on the target (`skip`, `overwrite`, `rename`).
- **Idempotent Import:** Re-running an import with `skip` or `overwrite` produces a consistent state.
- **Dry Run Mode:** Preview all import actions without making any changes to the target instance.
- **Secure:** Handles credentials via environment variables or CLI flags and never logs or exports sensitive information.
- **Reliable:** Implements exponential backoff and retries for network requests.
## Prerequisites
- Python 3.10+
- Access to source and target Metabase instances with appropriate permissions (API access, ideally admin).
## Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install metabase-migration-toolkit
```
After installation, the `metabase-export` and `metabase-import` commands will be available globally in your environment.
### Option 2: Install from TestPyPI (for testing)
```bash
pip install --index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple/ \
metabase-migration-toolkit
```
### Option 3: Install from Source
1. **Clone the repository:**
```bash
git clone <your-repo-url>
cd metabase-migration-toolkit
```
2. **Install the package:**
```bash
pip install -e .
```
## Configuration
1. **Configure Environment Variables (Recommended):**
Copy the example `.env` file and fill in your credentials. This is the most secure way to provide credentials.
```bash
cp .env.example .env
# Edit .env with your details
```
2. **Create a Database Mapping File:**
Copy the example `db_map.example.json` and configure it to map your source database IDs/names to the target database IDs.
```bash
cp db_map.example.json db_map.json
# Edit db_map.json with your mappings
```
**This is the most critical step for a successful import.** You must map every source database ID used by an exported card to a valid target database ID.
## Usage
### 1. Exporting from a Source Metabase
The `metabase-export` command connects to a source instance and exports its content into a local directory.
**Example using .env file (Recommended):**
```bash
# All credentials are read from .env file
metabase-export \
--export-dir "./metabase_export" \
--include-dashboards \
--include-archived \
--include-permissions \
--log-level INFO \
--root-collections "24"
```
**Example using CLI flags:**
```bash
metabase-export \
--source-url "https://your-source-metabase.com/" \
--source-username "user@example.com" \
--source-password "your_password" \
--export-dir "./metabase_export" \
--include-dashboards \
--root-collections "123,456"
```
**Available options:**
- `--source-url` - Source Metabase URL (or use `MB_SOURCE_URL` in .env)
- `--source-username` - Username (or use `MB_SOURCE_USERNAME` in .env)
- `--source-password` - Password (or use `MB_SOURCE_PASSWORD` in .env)
- `--source-session` - Session token (or use `MB_SOURCE_SESSION_TOKEN` in .env)
- `--source-token` - Personal API token (or use `MB_SOURCE_PERSONAL_TOKEN` in .env)
- `--export-dir` - Directory to save exported files (required)
- `--include-dashboards` - Include dashboards in export
- `--include-archived` - Include archived items
- `--include-permissions` - Include permissions (groups and access control) in export
- `--root-collections` - Comma-separated collection IDs to export (optional)
- `--log-level` - Logging level: DEBUG, INFO, WARNING, ERROR
### 2. Importing to a Target Metabase
The `metabase-import` command reads the export package and recreates the content on a target instance.
**Example using .env file (Recommended):**
```bash
# All credentials are read from .env file
metabase-import \
--export-dir "./metabase_export" \
--db-map "./db_map.json" \
--conflict skip \
--apply-permissions \
--log-level INFO
```
**Example using CLI flags:**
```bash
metabase-import \
--target-url "https://your-target-metabase.com/" \
--target-username "user@example.com" \
--target-password "your_password" \
--export-dir "./metabase_export" \
--db-map "./db_map.json" \
--conflict overwrite \
--log-level INFO
```
**Available options:**
- `--target-url` - Target Metabase URL (or use `MB_TARGET_URL` in .env)
- `--target-username` - Username (or use `MB_TARGET_USERNAME` in .env)
- `--target-password` - Password (or use `MB_TARGET_PASSWORD` in .env)
- `--target-session` - Session token (or use `MB_TARGET_SESSION_TOKEN` in .env)
- `--target-token` - Personal API token (or use `MB_TARGET_PERSONAL_TOKEN` in .env)
- `--export-dir` - Directory with exported files (required)
- `--db-map` - Path to database mapping JSON file (required)
- `--conflict` - Conflict resolution: `skip`, `overwrite`, or `rename` (default: skip)
- `--dry-run` - Preview changes without applying them
- `--include-archived` - Include archived items in the import
- `--apply-permissions` - Apply permissions from the export (requires admin privileges)
- `--log-level` - Logging level: DEBUG, INFO, WARNING, ERROR
## Permissions Migration
The toolkit now supports exporting and importing permissions to solve the common "403 Forbidden" errors after migration. See the [Permissions Migration Guide](doc/PERMISSIONS_MIGRATION.md) for detailed instructions.
**Quick example:**
```bash
# Export with permissions
metabase-export --export-dir "./export" --include-permissions
# Import with permissions
metabase-import --export-dir "./export" --db-map "./db_map.json" --apply-permissions
```
Raw data
{
"_id": null,
"home_page": null,
"name": "metabase-migration-toolkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "metabase, migration, export, import, backup, analytics, business-intelligence, bi-tools",
"author": "Metabase Migration Toolkit Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/00/03/20752a11fae5ad7029c94bad5a9187d5eed4a388a281e3cf110e39cea1ff/metabase_migration_toolkit-1.0.4.tar.gz",
"platform": null,
"description": "# Metabase Migration Toolkit\n\n[](https://github.com/YOUR_USERNAME/metabase-migration-toolkit/actions/workflows/tests.yml)\n[](https://codecov.io/gh/YOUR_USERNAME/metabase-migration-toolkit)\n[](https://badge.fury.io/py/metabase-migration-toolkit)\n[](https://pypi.org/project/metabase-migration-toolkit/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n\nThis toolkit provides two command-line tools, `metabase-export` and `metabase-import`, designed for exporting and importing Metabase content (collections, questions, and dashboards) between instances.\n\nIt's built to be robust, handling API rate limits, pagination, and providing clear logging and error handling for production use.\n\n## Features\n\n- **Recursive Export:** Traverses the entire collection tree, preserving hierarchy.\n- **Selective Content:** Choose to include dashboards and archived items.\n- **Permissions Migration:** Export and import permission groups and access control settings (NEW!).\n- **Database Remapping:** Intelligently remaps questions and cards to new database IDs on the target instance.\n- **Conflict Resolution:** Strategies for handling items that already exist on the target (`skip`, `overwrite`, `rename`).\n- **Idempotent Import:** Re-running an import with `skip` or `overwrite` produces a consistent state.\n- **Dry Run Mode:** Preview all import actions without making any changes to the target instance.\n- **Secure:** Handles credentials via environment variables or CLI flags and never logs or exports sensitive information.\n- **Reliable:** Implements exponential backoff and retries for network requests.\n\n## Prerequisites\n\n- Python 3.10+\n- Access to source and target Metabase instances with appropriate permissions (API access, ideally admin).\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install metabase-migration-toolkit\n```\n\nAfter installation, the `metabase-export` and `metabase-import` commands will be available globally in your environment.\n\n### Option 2: Install from TestPyPI (for testing)\n\n```bash\npip install --index-url https://test.pypi.org/simple/ \\\n --extra-index-url https://pypi.org/simple/ \\\n metabase-migration-toolkit\n```\n\n### Option 3: Install from Source\n\n1. **Clone the repository:**\n\n ```bash\n git clone <your-repo-url>\n cd metabase-migration-toolkit\n ```\n\n2. **Install the package:**\n\n ```bash\n pip install -e .\n ```\n\n## Configuration\n\n1. **Configure Environment Variables (Recommended):**\n Copy the example `.env` file and fill in your credentials. This is the most secure way to provide credentials.\n\n ```bash\n cp .env.example .env\n # Edit .env with your details\n ```\n\n2. **Create a Database Mapping File:**\n Copy the example `db_map.example.json` and configure it to map your source database IDs/names to the target database IDs.\n\n ```bash\n cp db_map.example.json db_map.json\n # Edit db_map.json with your mappings\n ```\n\n **This is the most critical step for a successful import.** You must map every source database ID used by an exported card to a valid target database ID.\n\n## Usage\n\n### 1. Exporting from a Source Metabase\n\nThe `metabase-export` command connects to a source instance and exports its content into a local directory.\n\n**Example using .env file (Recommended):**\n\n```bash\n# All credentials are read from .env file\nmetabase-export \\\n --export-dir \"./metabase_export\" \\\n --include-dashboards \\\n --include-archived \\\n --include-permissions \\\n --log-level INFO \\\n --root-collections \"24\"\n```\n\n**Example using CLI flags:**\n\n```bash\nmetabase-export \\\n --source-url \"https://your-source-metabase.com/\" \\\n --source-username \"user@example.com\" \\\n --source-password \"your_password\" \\\n --export-dir \"./metabase_export\" \\\n --include-dashboards \\\n --root-collections \"123,456\"\n```\n\n**Available options:**\n\n- `--source-url` - Source Metabase URL (or use `MB_SOURCE_URL` in .env)\n- `--source-username` - Username (or use `MB_SOURCE_USERNAME` in .env)\n- `--source-password` - Password (or use `MB_SOURCE_PASSWORD` in .env)\n- `--source-session` - Session token (or use `MB_SOURCE_SESSION_TOKEN` in .env)\n- `--source-token` - Personal API token (or use `MB_SOURCE_PERSONAL_TOKEN` in .env)\n- `--export-dir` - Directory to save exported files (required)\n- `--include-dashboards` - Include dashboards in export\n- `--include-archived` - Include archived items\n- `--include-permissions` - Include permissions (groups and access control) in export\n- `--root-collections` - Comma-separated collection IDs to export (optional)\n- `--log-level` - Logging level: DEBUG, INFO, WARNING, ERROR\n\n### 2. Importing to a Target Metabase\n\nThe `metabase-import` command reads the export package and recreates the content on a target instance.\n\n**Example using .env file (Recommended):**\n\n```bash\n# All credentials are read from .env file\nmetabase-import \\\n --export-dir \"./metabase_export\" \\\n --db-map \"./db_map.json\" \\\n --conflict skip \\\n --apply-permissions \\\n --log-level INFO\n```\n\n**Example using CLI flags:**\n\n```bash\nmetabase-import \\\n --target-url \"https://your-target-metabase.com/\" \\\n --target-username \"user@example.com\" \\\n --target-password \"your_password\" \\\n --export-dir \"./metabase_export\" \\\n --db-map \"./db_map.json\" \\\n --conflict overwrite \\\n --log-level INFO\n```\n\n**Available options:**\n\n- `--target-url` - Target Metabase URL (or use `MB_TARGET_URL` in .env)\n- `--target-username` - Username (or use `MB_TARGET_USERNAME` in .env)\n- `--target-password` - Password (or use `MB_TARGET_PASSWORD` in .env)\n- `--target-session` - Session token (or use `MB_TARGET_SESSION_TOKEN` in .env)\n- `--target-token` - Personal API token (or use `MB_TARGET_PERSONAL_TOKEN` in .env)\n- `--export-dir` - Directory with exported files (required)\n- `--db-map` - Path to database mapping JSON file (required)\n- `--conflict` - Conflict resolution: `skip`, `overwrite`, or `rename` (default: skip)\n- `--dry-run` - Preview changes without applying them\n- `--include-archived` - Include archived items in the import\n- `--apply-permissions` - Apply permissions from the export (requires admin privileges)\n- `--log-level` - Logging level: DEBUG, INFO, WARNING, ERROR\n\n## Permissions Migration\n\nThe toolkit now supports exporting and importing permissions to solve the common \"403 Forbidden\" errors after migration. See the [Permissions Migration Guide](doc/PERMISSIONS_MIGRATION.md) for detailed instructions.\n\n**Quick example:**\n\n```bash\n# Export with permissions\nmetabase-export --export-dir \"./export\" --include-permissions\n\n# Import with permissions\nmetabase-import --export-dir \"./export\" --db-map \"./db_map.json\" --apply-permissions\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Export and import Metabase content (collections, questions, dashboards) between instances",
"version": "1.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/Finverity/metabase-migration-toolkit/issues",
"Changelog": "https://github.com/Finverity/metabase-migration-toolkit/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/Finverity/metabase-migration-toolkit#readme",
"Homepage": "https://github.com/Finverity/metabase-migration-toolkit",
"Repository": "https://github.com/Finverity/metabase-migration-toolkit"
},
"split_keywords": [
"metabase",
" migration",
" export",
" import",
" backup",
" analytics",
" business-intelligence",
" bi-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fc7f36c5f781ecc197f6f0d482462ede68729b919f3621d43d6fa7be410407c3",
"md5": "d8c3edbd65b61fb5921d43a223da5ab6",
"sha256": "dc2c865692d4c7e50d1a91a48a27bc8a4597c1cb9632d050929b5d7bfcb50447"
},
"downloads": -1,
"filename": "metabase_migration_toolkit-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8c3edbd65b61fb5921d43a223da5ab6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 32395,
"upload_time": "2025-10-16T13:54:33",
"upload_time_iso_8601": "2025-10-16T13:54:33.538134Z",
"url": "https://files.pythonhosted.org/packages/fc/7f/36c5f781ecc197f6f0d482462ede68729b919f3621d43d6fa7be410407c3/metabase_migration_toolkit-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "000320752a11fae5ad7029c94bad5a9187d5eed4a388a281e3cf110e39cea1ff",
"md5": "fad69ff43b41bb2cea471df1488646fc",
"sha256": "74db236d98dad12c2f97f0e10069ff04b6f9ac42ef9a5b42154251abc577458f"
},
"downloads": -1,
"filename": "metabase_migration_toolkit-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "fad69ff43b41bb2cea471df1488646fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 64337,
"upload_time": "2025-10-16T13:54:35",
"upload_time_iso_8601": "2025-10-16T13:54:35.211654Z",
"url": "https://files.pythonhosted.org/packages/00/03/20752a11fae5ad7029c94bad5a9187d5eed4a388a281e3cf110e39cea1ff/metabase_migration_toolkit-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-16 13:54:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Finverity",
"github_project": "metabase-migration-toolkit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.28.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.64.0"
]
]
},
{
"name": "tenacity",
"specs": [
[
">=",
"8.1.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"0.20.0"
]
]
}
],
"lcname": "metabase-migration-toolkit"
}
JSON
