You are viewing documentation for the older version of YouTrack!

Skip to end of metadata
Go to start of metadata

Legend: (lightbulb) — new or updated topic

YouTrack Requirements

Which application servers does YouTrack support?

YouTrack distributed as a WAR file can be deployed into the following application servers:

  • Apache Tomcat 6+, 7+
  • Apache Geronimo
  • Mortbay Jetty
  • JBoss 4+
  • Caucho Resin
  • Glassfish

Distributed as a JAR file, YouTrack comes bundled with Mortbay Jetty.

Distributed as an EXE file, YouTrack comes bundled with Apache Tomcat 6.

Back to top

What hardware requirements does YouTrack have? (lightbulb)

Standalone version of YouTrack does not have specific hardware requirements. However, when choosing a hardware configuration to host YouTrack, keep in mind the following:

  • If you expect to have up to 10,000 issues in your installation, any up-to-date desktop PC can serve it.
  • Our own YouTrack instance currently (as of March 14, 2014) runs in Amazon EC2 environment, on a m2.4xlarge instance. It processes about 658 thousand issues in 105 projects. These issues contain about 690000 comments and 155000 attachments, of which about 107000 are images.

However, since YouTrack 5.0, requirements for allocated JVM memory have been increased:

  • The Permanent Generation Size must be set to at least 150Mb via the -XX:MaxPermSize parameter.
  • We recommend to start YouTrack with at least 512M of heap memory available.

Back to top

Does YouTrack support IIS?

Unfortunately, currently YouTrack does not support IIS, and we do not plan to implement IIS support in the near future.

However, you can set up Tomcat to run YouTrack, and configure your IIS to work with Tomcat. For more details, see

Please, note that it's not possible to use plain IIS because it's not a J2EE application server; and, in order to run YouTrack, you need a J2EE server in any case.

Back to top

Installation and Upgrades

Internet Explorer automatically renames JAR and WAR files to ZIP. What am I to do?

Nothing special, really:

  1. Download a JAR or WAR file.
  2. Rename to youtrack-xx.war or youtrack-xx.jar.
  3. Run your JAR file or deploy your WAR file as usual.

Back to top

How do I get YouTrack running on the same machine as TeamCity?

No special efforts are required to make YouTrack and TeamCity run together on a single machine. Both products can be deployed under most commonly used J2EE application servers. See below for the procedure of installing and running YouTrack in the same Tomcat instance TeamCity bundles.
Click here for the list of application servers supported by YouTrack. For guidelines on TeamCity integration, see Integration with TeamCity.

To run both YouTrack and TeamCity on the same machine with one HTTP server, you need to install both applications into the same Tomcat instance:

  1. Download and install TeamCity
  2. Download youtrack.war (instead of youtrack.exe)
  3. Rename <TeamCity installation directory>/webapps/ROOT folder into <TeamCity installation directory>/webapps/teamcity
  4. Drop youtrack.war into the <TeamCity installation directory>/webapps/ directory.
  5. Start Tomcat.
  6. TeamCity is now available at the http://<your_server>:80/teamcity, and YouTrack — at http://<your_server>:80/youtrack.

    Please check that baseURL is correct in the Administration > Settings page of your instance. For example, in this case baseURL should be http://<your_server>:80/youtrack. Correct baseURL is necessary for correct work of REST API, screenshot applet, OpenID and TeamCity integration and for correct links in YouTrack notifications.

    Back to top

How do I upgrade to a newer YouTrack build or version? Should I back up my database before upgrading?

First, you do not have to back up your database just to upgrade to a newer YouTrack build or version — after you have upgraded, YouTrack will find your database automatically.



You can track availability of YouTrack new builds right from Administrators UI. Check the 'Update info' panel on the Administration > Settings page. If a new build is available, you will see a link to download the update.

To upgrade to a newer YouTrack build or version:

  1. Stop YouTrack JAR, or YouTrack service (if you run YouTrack as Windows service), or, if you are running YouTrack within an application server, stop the server.
  2. Replace your old youtrack.jar or youtrack.war with a new build or version. Feel free to rename the new file to match the old one.
  3. Start YouTrack JAR or application server.

Back to top

I'm reinstalling (upgrading) YouTrack Windows service installation (using exe distribution) and get an error on installing Tomcat service. What's the problem?

This is a known issue (see Most often case for this error is when you run installation while the currently installed service is still running.

  1. If you're only going to reinstall YouTrack, please stop running YouTrack services before installation.
  2. If you've got the error already, please restart the PC. Then install YouTrack once again. The point is to delete Tomcat service marked for deletion during the first installation attempt (after which you've got the error).

Back to top

Importing Issues

Can I import issues from JIRA to YouTrack?

Yes, you can. To do that:

  1. Go to http://yourserver:port/jiraIntegration to open the JIRA Integration tab.
  2. Use links provided in the JIRA Integration tab to get one of two available YouTrack plug-ins depending on your JIRA version:
    • YouTrack plug-in for JIRA 3.8-3.9.3 (available at http://<yourserver>:<port>/_classpath/jira-plugin/jetbrains-charisma-rpc-plugin-3.8.1-3.jar)
    • YouTrack plug-in for JIRA 3.10-3.13.4 (available at http://<yourserver>:<port>/_classpath/jira-plugin/jetbrains-charisma-rpc-plugin-3.10-3.jar)
    • YouTrack plug-in for Jira 4.0 and higher (available at http://<yourserver>:<port>/_classpath/jira-plugin/jetbrains-youtrack-rpc-plugin-4.0.jar)
  3. Install the appropriate YouTrack plug-in in your JIRA instance by following guidelines for "Version 1" plug-ins in Managing JIRA Plugins.
  4. Make sure that remote API is enabled in JIRA and the YouTrack plug-in has appeared in the list of JIRA plug-ins as "Charisma JIRA plugin".
  5. Go back to http://yourserver:port/jiraIntegration.
  6. Click Enable JIRA Integration.
  7. Specify your admin-level credentials in JIRA, a project to import, and required issue types.
  8. Click Import Project.

Back to top

Can I import issues from other issue tracking systems?

Yes, YouTrack supports import from other tracking systems via REST API. We also provide Python Client Library, which wraps REST API and allows using it with Python scripts. In addition, the Python Client Library contains several ready-to-use scripts for importing issues from Bugzilla, FogBugz, Mantis, Trac, from Google Code Issue Tracker, and from another YouTrack server. In addition to these scripts, we provide another one, which enables importing issues to YouTrack via a CSV file, thus allowing import from almost any other issue tracker.

You can request other importing features.

Back to top

Which JIRA versions can I import my issues from?

JIRA 3.8 and later is currently supported.
Two separate YouTrack plug-ins for JIRA are provided: one for versions from 3.8 through 3.12 and another for version 3.13 and later. Both are bundled with YouTrack and are available from the Admin area at http://yourserver:port/jiraIntegration.

Back to top

Administering YouTrack

I got the java.lang.OutOfMemoryError exception. What should I do? (lightbulb)

The java.lang.OutOfMemoryError exception can be fixed by increasing the memory allocated for Java. To fix the error, identify the particular type of the

you've got. Depending on the exception reason, you should run YouTrack with the corresponding -D start Java parameter to solve the problem. Please refer to the table below:


Fix and Java Parameter


Java heap space

Increase heap size via -Xmx Java start parameter.

-Xmx1g sets allocated heap size to 1Gb

PermGen space

Increase permgen size via -XX:MaxPermSize.
Please note that YouTrack 5.0 requires at least 150Mb of allocated PermGen memory.


GC overhead limit exceeded

Increase heap size via -Xmx parameter.

-Xmx512m sets heap space to 512mb.

Back to top

I'm using the JAR format with the java service wrapper on a FreeBSD system, and cannot figure out how to specify what hostname YouTrack should bind itself on. What should I do?

To define a hostname for YouTrack, you have to edit file youtrack.jar!/jetbrains/mps/webr/standalone/runtime/standalone.xml. In the file, locate the block

and add the line <Set name="host">desired hostname</Set>. That's it!

For example, to set hostname to the, the block should look as follows:

(warning) If you get the error "JAR file signature violated":

If, after you change the content of JAR file, youtrack.jar won't start and you get the error "JAR file signature violated", then you need delete the violated signature:
youtrack.jar!/META-INF/JETBRAIN.SF and youtrack.jar!/META-INF/JETBRAIN.RSA files.

I have deployed YouTrack under Apache Tomcat but attempting to access YouTrack fails because of BeanCreationExceptions. What's the problem?

The user account used by Tomcat should have write permissions to Tomcat directory. Sometimes it doesn't, so make sure that the permissions are granted.

Solving the problem for YouTrack WAR under Apache Tomcat on Ubuntu.

By default, YouTrack creates database in the ${user.home}/teamsysdata folder.
Most likely, you are running tomcat under user account with $HOME pointing to /usr/share/tomcat6/ folder. Thus, YouTrack tries to create database folder /usr/share/tomcat6/teamsysdata and fails, because tomcat user has no write permissions for this folder.

To fix the problem, you can try any of the following methods:

  1. Grant write access to tomcat user for /usr/share/tomcat6 folder. Not recommended
  2. Change tomcat user $home folder to something like /home/tomcat and grant write access to it.
  3. Change the default database location. For detailed procedure, please refer to Changing Database Location page.

Back to top

What are the default user rights for Guest?

By default, the guest user has Observer role, which allows to Read Issues and Comments) for all projects.
To view actual permissions, which are currently set for the guest account, open the URL: http://<your youtrack url>/editUser/guest#user-tab=Permissions%20View

Back to top

How do I allow guest users to view my public projects?

  1. In the Admin Area, click Groups.
  2. Click All Users. This is a predefined group that controls permissions for all users including guests.
  3. Open the Roles tab.
  4. Click Assign role.
  5. In the Assign Role dialog box, select Observer in the Role drop-down list, and select your public projects in the Projects combo box.
  6. Click OK.

Back to top

How do I grant permissions to create new issues in a specific project to any registered user?

You should create or configure a user group that:

  • Allows to report issues within a specific project via "Create Issue" permission.
  • Enables Auto Join option, letting all new registered users join it automatically.
    Here's how to do that using predefined groups and roles:
  1. In the Admin Area, open the Groups tab.
  2. Click New Users. This is a predefined group that controls permissions for all registered users.
  3. In the Main tab, select Auto Join to automatically add all new registered users to this group.
  4. Open the Roles tab.
  5. Click Assign role.
  6. In the Assign Role dialog box, select Reporter in the Role drop-down list. In the Projects combo box, select projects where you want to enable any registered users to create new issues:
  7. Click OK to apply changes.

Back to top

I don't want to use root account, but it seems I cannot delete it. What should I do?

You cannot delete root account in YouTrack, but, if you prefer to use another account to administer YouTrack instance, configure new admin account properly, and then perform any or all of the following operations:

  • Deny root account any permissions.
  • Set a custom password for root account.
  • Ban root account.
    Taking these steps prevents unauthorized access using root account.

Back to top

I forgot my root password. How can I restore it?

To restore root password, run YouTrack with the -Djetbrains.charisma.restoreRootPassword=true JVM option. For example:

When YouTrack starts, the root user password and permissions will be reset to default values. Log in with the default credentials (root/root) and then set the new root password.

Back to top

How to restore my root password if I run YouTrack as Windows service?

To restore your root password, if you run YouTrack as Windows service, please follow these instructions:

  1. Stop the service
  2. In the command line, run
    This will cause Tomcat webserver properties manager to appear in your Windows system tray
  3. Click on the above mentioned manager and select 'Java' tab
  4. Add -Djetbrains.charisma.restoreRootPassword=true into Java options input
  5. Click OK. This will close the manager (Attention! This feels a bit counter-intuitive, but you really have to close it here)
  6. Open the manager once again. On General tab press Start
  7. Log in to YouTrack with root/root credentials
  8. Change the password
  9. Open the manager once again. On General tab press Stop
  10. Right click on manager's icon -> Exit
  11. Run the service as usual

Back to top

Why I don't see <some permission> on edit role page?

Make sure that you have this permission yourself. You can't grant a permission that you don't currently have.

Back to top

How do I create users in YouTrack?

Users are expected to register in YouTrack by themselves. However, if you need to create new user accounts yourself, you can do that using a regular registration form at http://yourserver:port/registerUserForm. After you have created a new user with this form, you are automatically logged in as this new user.
When you import an existing project from JIRA, user accounts are imported along with issues.

Back to top

How do I exclude a user from a group? There's no such option in group properties

You should exclude users from groups via user properties as opposed to group properties. See Administrator's Guide for details.

Back to top

I'm trying to change logging level for YouTrack but it shows unnecessary messages time and again. What am I doing wrong?

You should modify logging levels in webapps/youtrack-xx/WEB-INF/classes/jetbrains/charisma/main/log4j.xml (for Apache Tomcat). Modifying logging properties in other files won't affect YouTrack logs.

For more details, please refer to the Configuring Logging in YouTrack page.

Back to top

I want to allow attaching files larger than 10Mb set by default. How can I do that?

To specify the maximum allowed file size, use -Djetbrains.webr.maxUploadFileSize=<value> JVM property. The value should specified in bytes. For example, to limit the maximun allowed attachment size to 50Mb, you should specify:

Back to top

How to launch YouTrack without letting it open a browser window?

When you launch YouTrack as the jar file from the command line, it automatically opens a new browser window to display the main page. If you want to avoid launching the browser, you should use the "-Djetbrains.youtrack.disableBrowser=true" Java parameter to your command. For example:

Back to top

Using YouTrack

I'm trying to assign an issue to myself but YouTrack refuses to do so. What's wrong?

You are neither a member of any groups configured as assignees for a particular project nor an individual assignee for this project.
You have three options:

  • Ask the project lead that he/she assigns the issue to you.
  • Ask your administrator to add you to a group that is configured as assignee for the project.
  • Ask your administrator to configure your user account as an individual assignee for the project.

Both groups and individual assignees for a particular project can be configured by choosing Projects | <project name> | Assignees in the Admin area:

Back to top

YouTrack Screenshot applet does not start on Mac OS X 10.7 Lion! What's wrong?

If you encounter this problem, first of all check your Java preferences:

  1. Open Applications > Utilities > Java Preferences.
  2. In General settings select the 'Enable applet plug-in and Web Start applications' check box:
  3. Restart your browser.
    This simple procedure should solve the problem.

Back to top

I run YouTrack with Glassfish 3 and I cannot upload files or attach screenshots! WTF?!

Unfortunately, this is a known glassfish3 issue:
To fix it, download file web-core.jar and put it into <gf>/modules folder.

Back to top

Our workflow requires that developers mark issues as fixed and hand them over to QA. Is there a state in YouTrack that lets us do that, something like "Fixed not tested"?

Currently, in YouTrack 2.x, you can arrange the verification workflow using tags or custom fields.
With tags, you can organize the workflow via creating shared tags, and customizing notifications for the tags, so all the team members will be notified on time. See Fixed Not Tested in JetBrains Developer Community for guidelines.

With custom fields, an administrator can create a new custom field and attach it to the project. For example, your project can have a custom field "Verify state", with enum[1] type, and enumeration bundle of the following values: Fixed not Tested, Verifying, Verified, Not Verified, Back in development. The con of this method is that in YouTrack 2.x you cannot customize receiving notifications by one particular field update, and the workaround would be a simultaneous change of assignee along with updating such custom field, or a combination of custom fields and tags. For more details about custom fields please refer to the Custom Fields page.
The good news are that in the upcoming YouTrack Energy version we are going to provide a custom workflow support, please stay tuned for updates.

Back to top

I have an account in YouTrack, but now I want to log in using my OpenID. How can I associate my OpenID to my existing account?

First of all, log in to YouTrack with your OpenID. If your OpenID provider reports the same e-mail address as the one registered for your existing YouTrack account, then the OpenID will be automatically associated with the account.
If your OpenID e-mail address differs from the YouTrack account's e-mail, then upon login a new account will be created. In this case, YouTrack administrator should merge the new account with the existing one, so that OpenID will be associated to the existing user account.

Back to top

How do I search for issues, which were created/updated/resolved before specific date?

To search for a date before specific one, you can use search by a date range. For example, to find all unresolved issues assigned to you, which were created before January 12th, 2012, you can use the following search query:

Back to top

How do I order search results by anything other than "Updated"? (lightbulb)

Indeed, by default, search results are ordered by the "Updated" field, in descending order. That is, the most recently updated issue is displayed at the top of the list.
However, you can sort search results by any issue field.

First option is to specify sorting order in the search request itself. For example:

In this case search results will be sorted by Project name in ascending order (in case of project names, this means alphabetical order).

You can also sort search results by several parameters. In this case, issues will be sorted by the first parameter, and within the batch matching the first sort parameter, issues will be sorted according to the second sorting parameter.

Back to top

Is there an easy way to create multiple issues with the same set of attributes, tags etc.?

Of course there is!

  1. Create multiple new issues, one by one, without specifying their attributes.
  2. Search for your recent reported issues:
    by: me
  3. Select the recently reported issues that should have identical attributes and/or tags.
  4. Press Ctrl+Alt+J to open the Command window, and apply a single command to the selected issues.
    For example, the following command:
    for me project YouTrack subsystem Wiki priority normal fix for next version
    will assign all selected issues to you, move them to subsystem Wiki in project YouTrack, set them to normal priority, and schedule them to be fixed for next version.
  5. Press Ctrl+Enter to apply the command.

Back to top

Can I visually distinguish between features, bugs and other issue types in the list of issues?

Out of the box, YouTrack doesn't let you configure colors, custom formatting or other means of visually highlighting various issue types.
However, there's a workaround: you can mark different issue types with tags. For example, if you want to introduce custom highlighting for bugs and features, you might do the following:

  1. Search for unresolved bugs assigned to you:
    #unresolved for: me #bug
  2. In the list of issues, press Ctrl+A to select all issues (if the list of issues takes more than a single page, additionally click Select all issues in the yellow tooltip that appears just above the list of issues after you have pressed Ctrl+A.)
  3. Type command tag bug.
  4. Press Ctrl+Enter to apply the tag to selected issues.
  5. Execute steps 1-4 upon unresolved features assigned to you. To find them, enter #unresolved for: me #feature in the search box, and call the new tag "feature".
  6. For each of the two created tags, click the pencil icon in the Tags pane to modify their colors. For example, highlight "bug" with red and "feature" with blue:
  7. Click Settings in the toolbar and make sure that the Tags check box is selected in the Visibility tab:
  8. Search for all your unresolved features: #unresolved for: me. Both bugs and features are in the list of issues are now marked with tags corresponding to their type:

Back to top

Integration with External Tools

Does YouTrack support LDAPS? How can I configure integration for LDAPS?

Yes, YouTrack supports LDAPS (LDAP over SSL) protocol. For details about configuration, please refer to the LDAP integration page.

Back to top

I have some problems with my Mailbox Integration. How can I enable detailed logging?

To enable logging for Mailbox integration, in the file <YouTrack installation directory>/WEB-INF/classes/jetbrains/charisma/main/log4j.xml change the following code:


That's it!

Back to top

Integration with Version Control Systems

How to integrate YouTrack with different version control systems?

YouTrack can be integrated with version control systems via TeamCity 5.0 or later. For guidelines on TeamCity integration, see Integration with TeamCity.

Back to top

Does YouTrack integrate with version control systems directly, without using TeamCity?

No, it only integrates with VCS through TeamCity. TeamCity supports all major VCS's, including ClearCase, CVS, Perforce, StarTeam, Subversion, Team Foundation Server, Mercurial, and Visual SourceSafe.
TeamCity Professional Edition is available free of charge, making direct VCS support from YouTrack unjustified at this time.
Should TeamCity move their VCS support functionality into a separate module, we might reconsider this possibility.
For guidelines on TeamCity integration, see Integration with TeamCity.

Back to top

Make sure that your TeamCity installation successfully connects to your YouTrack installation.
See connection configuration guidelines in TeamCity 8.x documentation.

Back to top

Is it possible to integrate YouTrack with several TeamCity servers? How can I do it?

Yes, you can integrate YouTrack with several TeamCity servers.
To configure integration, open the TeamCity Integration section in the Admin area, add your TeamCity servers, and do not forget create correct mappings between YouTrack projects and TeamCity projects.

Back to top