This module allows to import/export taxonomies, structures or simple lists of terms into/from a vocabulary from/to a CSV file, a url or a copy-and-paste text.

CSV format is a simple list of values separated by a delimiter, often comma (,) or semicolon (;), and enclosures, often quotation marks ("). If you are unsure how to create a CSV file, you might want to use LibreOffice Calc or another spreadsheet application to export your data into a CSV file.

Specific import or export formats can be added simply by a plug-in mecanism (or ask author!).

After enabling the module, permissions "import taxonomy by csv" and "export taxonomy by csv" need to be set. Main "administer taxonomy" permission is not needed to use module, but this is recommended.

Internationalization is supported, except for attached Fields [Taxonomy CSV pour Drupal 7 only]. So you can import a list or a structure of terms, then translate them.

This module supports drush and allows to import or to export taxonomies by csv with command line interface.

Taxonomy CSV for Drupal 7 has got a simpler UI compared to the version for Drupal 6, because taxonomy has been reworked with fields in Drupal 7. Help for Drupal 6 version is available in English or in French.

Table of Contents

  1. Formats
    1. Structure
    2. Fields
    3. Term translation
  2. Import
    1. What to import (content of the source)?
    2. Where are terms to import?
    3. How is formatted your source?
    4. Which vocabulary do you want to import into?
    5. When a term exists, what to do with it?
    6. Informations on process and big taxonomies import
  3. Export
  4. Drush and Taxonomy csv import API
  5. Advanced settings and hints
    1. Permissions
    2. Other hints

1. Formats

Multiple formats can be used to import or export vocabulary. Except with some formats, the first column contains the term name. You can specify what you want to export and how additional columns should be imported.

To import a complex taxonomy, it's recommended to import terms in this order:

That's what you can choose in the first tab.

1. Structure

1. Terms (flat vocabulary)

Use this option to import a lot of terms in order to create a flat vocabulary. All items in your file will be imported as terms. Example:

2. Hierarchical tree structure or one term by line structure

Use this option to create a tree structure of a vocabulary (geography, classification...). To import a hierarchy with multiple parents as a genealogical one, it's advised to use "Polyhierarchy", "First level children" or "First level parents" imports.

Your file can be written with two schemes and a mixed one.
First scheme: Full ancestors of a term
In the first scheme, you need to set all ancestors to each term. The second column will be imported as the name of a child term of the term defined by the first column. The third column will be imported as a child of the second column, and so on. Lines can have any order. Example:
Be careful: when a child is added or updated, line should contain all its ancestors. So a third line may be:
but not:
because in this second case, < Mammal > is imported as a first level term and not as a < Animal > term child as in previous line.
Second scheme: One term by line
In the "one term by line structure" scheme, you can import terms without duplicate all its ancestor if previous term has ancestors. It is very useful with a spreadsheet application. It allows to easy build a structure and to upload a less heavy file. So your hierarchy can be:
World
Asia
Japan
Tokyo
Korea
Seoul
So, first lines of your csv file can be:
< Paris > will be automatically added as a child of < France > and so on.
Mixed scheme

Partial lines are allowed, so a next line can be:

< Switzerland > will be added as a child of < Europe > and of course < Bern > as a child of < Switzerland >.

In same way, above lines can be simplified to:

Full lines, partial and one term lines can be mixed, but order is important two by two lines, except when there are only full lines. In this example, if fifth and sixth lines are shift, < Seoul > will become a child of < Japan >.
3. Polyhierarchical structure

Use this option to create a a polyhierarchical structure, as a genealogy.
Format is the same than tree structure: each term is the child of previous item: parent, child, sub-child... and so on.
There are four differences. First, the first item doesn't need to be a root. Second, duplicate terms are always merged, except when one is the direct parent of the other one, because it's forbidden in Drupal. So, if the vocabulary is monohierarchical and without non-direct duplicate terms, as in the previous geographical example, result is the same than with previous option. Third, lines can be partial too, but in some case of duplicates, result may differ. Last, polyhierarchy can be recursive.
For example, lines may be:

2. Fields

Terms are imported with a csv scheme provided by the user.

1. Fields CSV format

The csv scheme should contain each column header of the csv input. The column header is the name (not the label) of the field where to import items into. It can be a default header (name, description, weight, vid, vocabulary_machine_name, guid) or a custom field. The first item is always the name or the tid of a term.

For example, you want to import a list of car makers, and you would like each car maker to have custom fields indicating nationality and date of origine(origine of example, fictional):

So, with 'Fields' format, you can set your format:

name, field_country, field_year_started

or more generically:

name, field_mycustomfield_1_machinename, field_mycustomfield_2_machinename...

Items can be repeated for multivalued fields.

name, description, weight, parent, synonym, synonym, synonym, related_term, related_term, related_term, related_term

The module supports all field types as long as they have a 'value' in their definition. These fields has been checked:

2. Autocreation of Fields

Custom fields are automatically created if they don't exist and then attached to the vocabulary. By default, a 'text' field is created when the field doesn't exist. If you want to create another type of field, you have to set it with "|" symbol in the vocabulary section of the form. The field is not created or modified if it exists.

For exemple, you want to import these items (origine of example):

Your custom format will be:

name, field_internal_name, description, field_file, field_status, related_term, related_term, related_term

Your custom fields will be:

field_file|file, related_term|taxonomy_term_reference

3. Term translation

Translation is available only if i18n is installed and the submodule i18n Taxonomy is enabled. Furthermore, the i18n mode of the vocabulary should be "Translate" or "Localize".

Warning: If you have a tree structure, you should import it before fields or translations, and for each translation if you use a full Translate mode.

Format: The term is in the first column followed by its translations. If the i18n mode is Localize, then description and translated descriptions can be added.

For vocabulary with Translate mode:

term name/id, first translated term name, second translated term name...

For vocabulary with Localize mode:

term name/id, first translation of term name... , description, first translation of description...

Examples:

Notes

2. Import

Taxonomy CSV allows to import structure and properties of terms.

1. What to import (content of the source)?

Source can be configured with the first field set. See formats.

2. Where are terms to import?

You can import your terms from a file or with a text area. Simply check your choice. File can be a local file path or a url.

3. How is formatted your source?

Import need to be utf-8 formatted, without byte order mark in preference.

This group of settings allows to set non standard delimiter and enclosure and specific locales, such as "fr_FR.utf8".

4. Which vocabulary do you want to import into?

You can import your terms in a existing vocabulary or create a new one. You can import your terms too in an existing vocabulary.

When you want to import a new taxonomy into an existing one, it is recommended to process in two steps in order to check import.

If you only want to create a new vocabulary, the first choice is sufficient, unless when you have multiple files for one vocabulary.

5. When a term exists, what to do with it?

Destination can be configured with the next field set. You can specify what will become existing terms when you import a term with the same name.

6. Informations on process and big taxonomies import

This group of options allows to choose informations displayed at end of process.

To import big taxonomies (from 1000 or 10000 lines depending on the server) when access to time and memory settings of server are forbidden, it is recommended first to disable some other taxonomy related modules as "pathauto" before import. Settings aren't lost when you disable a module - and not uninstall it -. After import process, modules can be reactivated.
Next, you can use these tweaks (in groups of options).

3. Export

Taxonomy CSV allows to export structures and properties of terms of one or all vocabularies.

Simply choose what you want to export (see formats) and how to export. Some formats may be unavailable.

4. Drush and Taxonomy csv import API

This module supports drush: you can import/export taxonomies from the command line interface with drush taxocsv-import and drush taxocsv-export. See command line help for more information.

More generally, this module can be used as an API. You can use the full module as a dependance or directly in your module. Import is run as this:

$csv_lines = '"Europe", "France", "Paris"';
$csv_lines .= "\n". ',, "Lyon"';
$csv_lines .= "\n". ',"United Kingdom", "London"';
$csv_lines .= "\n". ',"Portugal", "Lisbonne"';
$result = taxonomy_csv_import(
array(
'text' => $csv_lines,
'import_format' => 'tree',
'update_or_ignore' => 'update',
));

Or as this (line level import):

$result = taxonomy_csv_line_import(
array("Europe", "France", "Paris"),
array(
'import_format' => 'tree',
'vocabulary_id' => 2,
'update_or_ignore' => 'update',
));

Possible formats are explained in comments or above. Some may be unavailable.

Taxonomy Builder API can be more convenient in some cases. Choice depends on your needs. Taxonomy CSV is designed as a run-once module with checks and multiple formats, while Taxonomy Builder is a permanent, light and quick module. A full explanation of the differences in design can be found here.

5. Advanced settings and hints

1. Permissions

To import/export terms, user needs 'Import taxonomy by CSV' and 'Export taxonomy by CSV' rights.
Furthermore, user needs general taxonomy permissions (Drupal 6) or taxonomy permissions (Drupal 7). These permissions are often associated with access rights for administration pages.

2. Other hints

Another Drupal module allows CSV import too, despite its name: taxonomy XML. Its approach is different: it uses one file compliant to thesauri standard ISO 2788, i.e. a three columns csv file: term, type of link (relation, description, synonym...), item, or, for specialists, subject, predicate, object. Additional fields are managed as the third one.

Taxonomy manager can be used too.

For export, you can use Taxonomy XML too or one of backup modules. Taxonomy CSV is a more specialised tool which allows more precise tuning.