---
title: Contentstack Command-line Interface (CLI) - Taxonomy Migration
description: Use the Taxonomy Migration utility to import taxonomies and terms into a stack using a CSV file.
url: https://www.contentstack.com/docs/developers/cli/taxonomy-migration
product: Contentstack
doc_type: cli-guide
audience:
  - developers
version: v1
last_updated: 2026-03-26
---

# Contentstack Command-line Interface (CLI) - Taxonomy Migration

This page explains how to use the Contentstack CLI Taxonomy Migration utility to import taxonomies and their terms into a stack from a CSV file. It is intended for developers or administrators who manage Contentstack stacks and need to migrate taxonomy data using the CLI.

## Taxonomy Migration

With the Taxonomy Migration utility, you can **import the taxonomies** and respective terms using a CSV file created using one of the following methods:
- [export-to-csv](/docs/developers/cli/export-content-to-csv-file) plugin
- [CSV template](https://github.com/contentstack/cli/blob/main/packages/contentstack-migration/examples/taxonomies/test_taxonomies.csv)

This step-by-step guide lets you use the Taxonomy Migration utility to perform the taxonomy migration operation on a stack.

## Prerequisites
- [Contentstack account](https://www.contentstack.com/login/)
- [CLI installed](/docs/developers/cli/install-the-cli/) and [configured](/docs/developers/cli/configure-regions-in-the-cli/) (version 1.11.0 and above)
- [CLI authenticated](/docs/developers/cli/cli-authentication/)
- CSV file (generated using the [export-to-csv](/docs/developers/cli/export-content-to-csv-file) plugin or a [CSV template](https://github.com/contentstack/cli/blob/main/packages/contentstack-migration/examples/taxonomies/test_taxonomies.csv))

**Note:** If you are using a CSV template to generate the CSV file, the `Taxonomy Name` and `Term Level* Name` fields are mandatory.

**Additional Resource:** Here is a [sample script](https://github.com/contentstack/cli/blob/main/packages/contentstack-migration/examples/taxonomies/import-taxonomies.js) to import taxonomies into your stack. Preferably, use this sample script to try out the commands in this guide.

## Usage

```
csdx cm:stacks:migration --file-path  --config data-dir: --stack-api-key
```

## Options
- `-k`, `--stack-api-key=stack-api-key`: Stack API key.
- `--config=config`: [Inline configuration] The key for receiving data-dir and delimiter. To provide the path of the CSV file in the data-dir, use `data-dir:<value>`. If you used a delimiter while exporting or manually creating taxonomies to CSV, use `{data-dir:<value>,delimiter:<value>}`.
- `--file-path=filepath`: Path where the taxonomy migration files are stored.

**Tip:** Preferably, use the sample [taxonomy migration script](https://github.com/contentstack/cli/blob/main/packages/contentstack-migration/examples/taxonomies/import-taxonomies.js) to import taxonomies.

## Example

Without delimiter:

```
csdx cm:stacks:migration -k b*******9ca0 --file-path "../contentstack-migration/examples/taxonomies/import-taxonomies.js" --config data-dir:'./data/Taxonomy Stack_taxonomies.csv'
```

**Note:** For Windows OS, use "`\`" instead of "`/`" for paths.

With delimiter (Mac OS):

```
csdx cm:stacks:migration -k b*******9ca0 --file-path "../contentstack-migration/examples/taxonomies/import-taxonomies.js" --config {data-dir:'./data/Taxonomy Stack_taxonomies.csv',delimiter:'|'}
```

With delimiter (Windows OS):

```
csdx cm:stacks:migration -k b*********d4 --file-path "C:\Users\v***h\Desktop\Contentstack\CLI\Taxonomy\import-taxonomies.js" --config data-dir:'C:\Users\v***h\Desktop\Contentstack\CLI\Taxonomy\test_taxonomies.csv' delimiter:','
```

## Steps for Execution
Follow the steps below to run the taxonomy migration command:
- Provide the following flags in the `cm:stacks:migration` command to import taxonomy:File path that contains the taxonomy migration files.

**Note:** Provide the file path of the downloaded [sample script](https://github.com/contentstack/cli/blob/main/packages/contentstack-migration/examples/taxonomies/import-taxonomies.js).
- Stack API key
- Config that contains the CSV file path and the delimiter

**Note:** You must provide a delimiter in config only if you used a delimiter while exporting taxonomies to CSV or generating CSV file manually.

```
csdx cm:stacks:migration --stack-api-key  --file-path  --config {data-dir:,delimiter:}
```

**Note:** For Windows OS, use '`,`' as the delimiter.
- Run the command in your terminal.

You have successfully migrated taxonomies from your CSV file to the provided stack.

Without delimiter:

With delimiter (Windows OS):

With delimiter (Mac OS):

## Troubleshoot
If you are facing a **Migration Unsuccessful** or **Module cannot be found** error, please try one of the following troubleshooting methods:
- **Troubleshoot in your current terminal session**:**Windows (CMD)**:
```
FOR /F "usebackq tokens=*" %i IN (`npm root -g @contentstack/cli`) DO SET NODE_PATH=%i/@contentstack/cli/node_modules
```

- **Windows (PowerShell)**:
```
foreach ($i in $(npm root -g @contentstack/cli)) { $env:NODE_PATH = "$i/@contentstack/cli/node_modules" }
```

- **Mac/Unix**:
```
export NODE_PATH="$(npm root -g @contentstack/cli)/@contentstack/cli/node_modules"
```

- **Troubleshoot in the entire session**:
```
npm link fast-csv
```

## Common questions

### What CSV files can I use for taxonomy migration?
You can use a CSV file generated using the [export-to-csv](/docs/developers/cli/export-content-to-csv-file) plugin or a [CSV template](https://github.com/contentstack/cli/blob/main/packages/contentstack-migration/examples/taxonomies/test_taxonomies.csv).

### When do I need to specify a delimiter in `--config`?
You must provide a delimiter in config only if you used a delimiter while exporting taxonomies to CSV or generating CSV file manually.

### Which fields are mandatory when using the CSV template?
If you are using a CSV template to generate the CSV file, the `Taxonomy Name` and `Term Level* Name` fields are mandatory.

### What should I try if I see “Migration Unsuccessful” or “Module cannot be found”?
Try the troubleshooting methods listed under **Troubleshoot**, including setting `NODE_PATH` for your terminal session or running `npm link fast-csv`.