Bulk Importing Taxonomy Terms in Drupal Using Custom Drush Command

| | 2 min read

Drupal now has a robust configuration management system, allowing the management of configurations as code. This supports the transition of code between multiple environments, such as Dev -> Testing -> Staging -> Production, in a seamless manner. A notable challenge arises with taxonomy terms; they aren't exported like other configurations, complicating the synchronization of specific taxonomies across environments.

Fortunately, there's a solution. Drush, Drupal's command-line tool, offers a way to address this. This article will guide you through the creation of a custom Drush command to bulk-import taxonomy terms, ensuring synchronization from development to production.

Step 1: Create a New Drupal Module

Location: modules/custom/taxonomy_term_import

Kick off the process by creating a module. This module will encompass our custom Drush command.

name: 'Taxonomy Term Import'
type: module
description: 'Drush Command to Sync Terms from Vocabulary 1, 2, 3'
core_version_requirement: ^8.8 || ^9 || ^10
package: 'Custom Drush Commands'



Step 2: Code to Import Taxonomy Terms

Location: taxonomy_term_import/src/Commands/TaxonomyTermImport.php

This class embeds the logic for our Drush command.

namespace Drupal\taxonomy_term_import\Commands;
use Drush\Commands\DrushCommands;
use Drupal\taxonomy\Entity\Term;
 * Import taxonomy terms.
 * @command import_taxonomy_terms
 * @usage import_taxonomy_terms
 *   Import the specific set of taxonomy terms using this command.
public function importTaxonomyTerms() {
  // Define the taxonomy terms to be imported.
  $terms = [
    ['name' => 'Organization', 'vid' => 'topic_category'],
    ['name' => 'People', 'vid' => 'topic_category'],
    ['name' => 'Initiative', 'vid' => 'topic_category'],
  // Iterate over each term to check if it exists and then add if necessary.
  foreach ($terms as $term_data) {
    $term_name = $term_data['name'];
    $taxonomy_machine_name = $term_data['vid'];
    // Check for the term's existence.
    $term_exists = \Drupal::entityTypeManager()
        'name' => $term_name,
        'vid' => $taxonomy_machine_name,
    // If it doesn't exist, add it.
    if (empty($term_exists)) {
      $term = Term::create($term_data);

The annotations (@command and @usage) specify the name and usage of our Drush command, respectively.

Step 3: Register the Command with Drush

Create a drush.services.yml file in your module's root.

Location: modules/custom/taxonomy_term_import/drush.services.yml

Add the following configuration to this file:

    class: \Drupal\taxonomy_term_import\Commands\TaxonomyTermImport
      - { name: drush.command }

This configuration registers our custom Drush command with Drupal.

Step 4: Clear Cache

Upon completing the above steps, you must clear Drupal's cache to allow system recognition of your command

drush cr

Step 4: Ready To Import The Terms

Execute the newly created drush command to import the terms

drush import_taxonomy_terms

Watch our Developer Blog to see similar tips and solutions.