YouTrack Standalone 2017.4 Help

Import from a CSV File

You can import issues into YouTrack from a comma-separated values (CSV) file. This option lets you import data from any issue tracker that can export issues in CSV format. Use this option to import issues from Trello (Business Class and Enterprise), Asana, GitHub, GitLab and many others.

This procedure requires the following steps:

  1. Set up your local environment.
  2. Prepare your import files.
  3. Map the fields in your CSV file to issue attributes in YouTrack.
  4. Import your issues.

Import Details

If the import file contains references to entities that do not already exist in YouTrack, they are created. The user account that you use to run the import should have permission to create projects, issues, users, and possibly more. We recommend that you use an account with a System Admin role to execute the import script.

New entities are created as follows:

ProjectsIf the project that is referenced in the source file does not already exist, a new project is created.
  • The project name and ID are assigned based on the values from the CSV file.
  • The user who executes the import script is set as the project lead.
UsersSeveral issue attributes like reporterName and Assignee store references to user accounts. The values in the source file are checked against existing user accounts by Login. For each new value that does not match the login for an existing user, a new user account is created.
  • If the source file contains a single value, this value is set as the full name, login, and is used as the local part for an email address with the domain Whitespace characters are replaced with underscores.
  • You can specify attributes for new users by formatting the data in each field as login;fullName;email. In this case, whitespaces that are mapped to the full name are preserved.
  • All new user accounts are assigned randomly-generated passwords.

References to users in the import file are mapped to existing accounts in YouTrack. If a match is not found, a new user account is created.

Imported users are allocated a license according to your subscription plan. For users that exceed your per-user license limit, the imported users are flagged as banned.

For more information, see Ban User Accounts.

Custom FieldsIf the source file contains a field that does not exist in YouTrack and the issues are imported into an empty project, the custom field is created and added to the target project.
  • The field name and type are set according to the definitions in your mapping file.
  • The properties for the custom field are set as follows: autoAttached=true, isPrivate=false, defaultVisibility=false.
If you import into a project that already contains issues, the non-existing fields are created as defined in the mapping file, but the fields are not added to the target project and their values are not imported.
Field ValuesIf the source file contains new values for an existing field, they are added to the current set of values.

Set Up Your Environment

Import to YouTrack is supported by the YouTrack Python Client Library. This library is basically a wrapper for the YouTrack REST API. You won't actually need to do any programming in Python, but you do need to install Python and download the client library.

To set up your environment:

  1. Download and install Python. The Python Client Library is compatible with Python 2.7+. Python 3 releases are not supported. You can choose whichever installation directory you prefer.

    The latest versions of macOS, CentOS, Red Hat Enterprise Linux (RHEL), and Ubuntu come with Python 2.7 out of the box. If you're working with any of these operating systems, continue with the next step.
  2. Download the latest version of the YouTrack Python Client Library from GitHub.
  3. Extract the contents of the ZIP archive to a folder in your local directory. You can extract the files to whichever folder you prefer.

Prepare Your Import Files

One of the most important steps in this procedure is to know exactly what you are going to import into YouTrack. You should inspect your import files and verify that the data is formatted properly. The following sample shows sample data that can be imported into YouTrack.

"Issue ID","Project ID","Project","Type","Priority","State","Subsystem","Module","Reporter","Assignee","Reviewer","Created","Updated","Summary","Description","CustomFieldString","CustomFieldDate" SA-1,SA,SomeApp,Task,Critical,In Progress,UI,Admin Console,Marco Fu,John Higgins,Neil Robertson,2011-03-01 16:55:00,2011-03-02 17:54:00,"Issue 1","Description for issue 1","Start",2011-03-02 18:00:00 SA-2,SA,SomeApp,Bug,Major,Open,Core,,John Higgins,Marco Fu,Neil Robertson,2011-04-01 17:55:00,2011-04-02 18:54:00,"Issue 2","Description for issue 2",,2011-04-02 19:00:00,"Comment 2.1","Comment 2.2" SA-3,SA,SomeApp,Bug,Normal,Fixed,Core,Main,Neil Robertson,Mark Allen,Neil Robertson,2011-04-02 17:55:00,2011-04-03 18:54:00,"Issue 3","Description for issue 3","PX-1",2011-04-03 19:00:00,"Comment 3.1","Comment 3.2" SA-4,SA,SomeApp,Task,Normal,Fixed,UI,User Profile,Neil Robertson,Mark Allen,Mark Williams,2011-04-02 13:55:00,2011-04-03 14:54:00,"Issue 4","Description for issue 4","PX-2"

To ensure that your import is successful, follow these steps:

  1. Open your CSV file in a spreadsheet editor. It's much easier to read and, if necessary, modify the data when it is presented in discrete columns and rows.
  2. Check the first row (record) in the file. This record should be a header that contains a list of field names.
  3. Check your header for required fields. Your header must include fields that can be mapped to each of the following issue attributes: project_id, project_name, numberInProject, reporterName, created, and summary. If these columns are not present, add them to your CSV file.

You might also consider whether it's safe to import your data into an existing project. If you're not entirely sure about the contents of your CSV file, you can update the values in the Project ID and Project columns to import your data into a new, empty project instead.

Importing Comments

You also want to verify how your source application exports comments. Many applications export comments as fields that do not have a field name in the header. This format is illustrated in the following example:

"Issue ID","Project ID","Project" "1","SA","SomeApp","This column doesn't have a field name in the header, so it becomes the first comment","this becomes the second comment","and this becomes the third."

Comments in this format are imported without any related attributes. These attributes are generated during import.

  • Comments are added on behalf of the guest user account.
  • The comment date is set to the current date and time.

The client library lets you import comments that are stored in separate CSV files. If you have the possibility to extract this data and format it correctly, you can import comments with attributes and issue attachments.

For comments, the CSV file must contain the following fields in the specified order:


For the field names in the header, you can specify any value you want, but the field name for the comment text should be empty. The most important requirement is that you present these fields in the specified order. For each comment, the project ID and issue number must correspond to a record in the CSV file that contains your issue data.

Use the following example as a guide.

"Issue ID","Project ID","Project" "SA","1","judd;Judd Davidson;","2011-03-01 17:55:00 MSK","This column doesn't have a field name in the header, so it becomes the first comment", "SA","1","ronnie;Ronnie;","2011-03-01 17:56:00 MSK","this becomes the second comment", "SA","1","David","2011-03-01 17:57:00 MSK","and this becomes the third."

Importing Attachments

You also have the ability to import issue attachments from a separate CSV file.

For attachments, the CSV file uses the following format:


For the field names in the header, you can specify any value you want, but the field name for the path to the attachment files should be empty. The most important requirement is that you present these fields in the specified order. For each attachment, the project ID and issue number must correspond to a record in the CSV file that contains your issue data.

Use the following example as a guide.

"SA",1,"Marco Fu","2015-10-20 21:00:00","/home/user/tmp/comments.csv" "SA",1,"Marco Fu","2015-10-20 22:00:00","/home/user//tmp/attachments.csv" "SA",5,"John Higgins","2015-10-20 21:00:00","/home/user/pictures/bear.jpg" "SA",5,"John Higgins","2015-10-20 22:00:00","/home/user/pictures/flowers.jpg"

Build Your Mapping File

The next step is to map the fields in your source file to issue attributes in YouTrack. The client library contains a sample file that you can customize to match your import data. The file is saved as in the python/csvClient subfolder of the client library. This file contains mappings for all of the fields that are required for successful import and definitions for most custom field types.

The following sample file has been customized to map fields that are defined in the sample CSV file from the previous step in this procedure.

import csvClient csvClient.FIELD_NAMES = { "Project ID" : "project_id", "Project" : "project_name", "Summary" : "summary", "Reporter" : "reporterName", "Created" : "created", "Updated" : "updated", "Description" : "description", "Issue ID" : "numberInProject", "Subsystem" : "Subsystem", "Module" : "Module", "Assignee" : "Assignee", "Reviewer" : "Reviewed by", "CustomFieldString" : "Iteration", # Map the column "CustomFieldString" to the "Iteration" field. "CustomFieldDate" : "Planned Date" # We can skip mappings for default fields like Type, Priority, State. } csvClient.FIELD_TYPES = { "Subsystem" : "ownedField[1]", "Module" : "enum[1]", "Assignee" : "user[1]", "Reviewed by" : "user[1]", "Planned Date" : "date", "Iteration" : "string", # Define type for field "Iteration". } csvClient.CSV_DELIMITER = "," csvClient.DATE_FORMAT_STRING = "%Y-%m-%d %H:%M:%S"

To build your mapping file:

  1. Either open the file or open a new file in a text editor and paste the content of the sample mapping file provided here. The first line of the file must read import csvClient.
  2. In the csvClient.FIELD_NAMES section of the file, map all of the fields from your source file to their corresponding issue attributes in YouTrack. Pay attention to the following guidelines when you map your fields:
    • The left side of the mapping references the field name in your CSV file. These values must be specified exactly as written in the header.
    • The right side of the mapping references an issue attribute in YouTrack. Base attributes use the attribute names that are specified in the Import REST API. For mappings to custom fields, use the custom field name.
    • The mapping file must contain mappings for all of the following issue attributes: project_id, project_name, numberInProject, reporterName, created, and summary. If any of these fields are not included in the mapping, the import fails with an error.
    • If the column names in the source file match the default names for target custom fields in YouTrack, you don't need to map them explicitly. This includes default fields like Type, Priority, and State. You should, however, verify that the data that is stored in the source file matches the data type for the target field.
    • Each field in your source file can only be mapped to a single target field. For example, you cannot map the issue summary to both the issue summary and description.
  3. In the csvClient.FIELD_TYPES section of the file, specify the data type for fields that are created during import. Consider the following guidelines:
    • The left side of the mapping references the name of the custom field in YouTrack. These values must exactly match the custom field name in the FIELD_NAMES dictionary.
    • The right side of the mapping references the field type in YouTrack. For a list of valid types, refer to the Administration REST API.
    • If the target field already exists in YouTrack, you do not need to include it here.
    • You cannot change the data type of an existing field. For example, if the existing Assignee field stores single values (user[1]), you cannot use user[*] in the mapping file and import multiple assignees. You must first update this property for the Assignee field in the YouTrack user interface, then import the data.
  4. For the csvClient.CSV_DELIMITER, enter the delimiter character that is used in your CSV file. If the delimiter in your CSV file and the character that is specified for this parameter are not the same, the import fails.
  5. For the csvClient.DATE_FORMAT_STRING, specify the format that is used for date fields in your CSV file. This parameter accepts directives that are used by the strftime(format) method in the Python Standard Library. You can find a complete list of directives in the Python documentation.
    • In our sample mapping file, the %Y-%m-%d %H:%M:%S pattern recognizes date values in the format 2015-10-20 21:00:00.
    • The file uses the pattern %A, %B %d, %Y %I:%M:%S %p %z, which recognizes date values in the format Tuesday, October 20, 2015 09:00:00 PM +0300.

    Just look at the format that is used in your CSV file and replace each value with the corresponding directive. Enter punctuation marks and whitespace between directives as they appear in your fields.

  6. Save your mapping file with the extension .py and add it to the <unzipped library directory>\python\csvClient directory.
  7. Open the file in the python subfolder of the client library.
  8. Locate the reference to the csvClient module and set the value to the name of your mapping file (without the .py extension). Use the following example as a guide:
    import os import re import calendar import time import datetime import sys import csvClient from csvClient.client import Client import csvClient.<mapping file name> import youtrack from youtrackImporter import *
  9. Save and close the file.

Import Your Data

The last step is to run the command that imports your data from the CSV file.

To import your data:

  1. Open the command-line interface that is supported by your operating system.
  2. If necessary, change the current directory to the installation directory for Python. For example (Windows):
    cd C:\Python27
  3. Enter the following command:
    python source_file target_url target_login target_password comments_file attachments_file
    Replace the command-line parameters with values as described here:
    source_fileThe full path to the source CSV file.
    target_urlThe base URL of the target YouTrack server. For YouTrack InCloud instances, your base URL includes the trailing /youtrack. For example:
    target_loginThe login for a YouTrack administrator account.
    target_passwordThe password for the YouTrack administrator account.
    comments_fileOptional. The full path to the CSV file that contains issue comments.
    attachments_file Optional. The full path to the CSV file that contains references to attachments.
    • The command executes the Python import script.
    • If successful, the following line is printed in the command-line interface for each issue:
      Issue [ <issue ID> ] imported successfully
  4. Check the project or projects that you imported issues into and verify that the data is presented properly. If you are not satisfied with the results and want to re-import the data:
    • Delete all of the issues that were created during import. If you imported issues into a new project, simply delete the project.
    • Edit your source file and/or mapping file.
    • Run the import script again.


If you encounter any errors when you run the import script, see if any of the following conditions apply.

ConditionError for [/user/login]: 302: Moved Temporarily
CauseThe value that you used for the target_url parameter is incorrect. The most common mistake is to enter the base URL for a YouTrack instance without /youtrack at the end of the URL.
SolutionChange the value of the target_url parameter and run the import the script again. Use the value that is shown as the Base URL setting for your YouTrack service.
  1. For YouTrack Standalone, copy the value from the Base URL setting on the Global Settings page.
  2. For YouTrack InCloud, copy the value from the Base URL setting on the Domain Settings page.
ConditionError for [<resource>]: 403: Forbidden: You have no permissions for <resource>
CauseThe user account that you used to run the import script does not have permission to read or update the target resource. The resource URL indicates which entity is not accessible to the user.
SolutionRun the import script with a user account that has sufficient permissions to update the target resource.
Last modified: 4 January 2018