How do I run Jalview?

You need a computer that can run at least Java 1.7 to use the full Jalview application(unfortunately this excludes users with older Macs - sorry). If java is installed, then the ‘Launch Jalview Desktop’ link at the top should work (if your browser asks you to save the application-x-jnlp file or choose an application to run it with, look for ‘Java Web Start’, or locate your java installation directory and look for the javaws binary). You can also go to the Install Anywhere Web Installer download area area to get an installer for your platform.

If you have Java 1.8 or later on in your browser (Firefox still provides this), you can try the web based version of Jalview - JalviewLite - right now by going to the applets page. The web based version doesn’t let you print or access web services, but includes most of Jalview’s core functionality.

Linux users: To launch jalview_via_webstart on openJDK from your browser, you will need to install icedtea-netx, which provides the javaws binary.

How do I edit sequences in Jalview?

Use the Mouse

Use the cursor keys

Edit Selected Region Only

Press F2 to enter Keyboard Mode

Can I install Jalview on a server?

Yes! Just remember to include the ‘-nodisplay’ flag on the command line (and if in doubt, also include _java -Djava.awt.headless=true_to tell Java not to attempt to use the graphics environment)

For example:

java -Djava.awt.headless=true .. jalview.bin.Jalview -nodisplay -open ...

The latest version of Jalview should run fine on a server without a graphics environment, but some operations may fail. If you encounter problems, submit a bug report.

How do I get the consensus sequence for an alignment?

Right-click on the ‘Consensus’ label for the consensus annotation track, and select “Copy consensus sequence”.

How do I increase the memory available to Jalview?

Full instructions for different operating systems and installations are here. If yours isn’t listed, drop us a line at the help address.

F2 key does not toggle Cursor mode on my Mac?

You may be using a keyboard which has visual / audio settings mapped onto the Function keys. You must press the “Fn” key, together with F2 key to toggle Cursor Mode.

Can I run Jalview from the command line?

Yes. The Jalview Desktop has a number of command line options, and recent versions of the Jalview Desktop application come with a command line tool ‘jalview’ that allows you to call it from the command line.

Open a command prompt or terminal and try:

jalview -help

This should list the current set of arguments Jalview supports. The online documentation also includes a list of jalview command line parameters

Note: This FAQ has been updated - we no longer recommend the -Djava.ext.dirs=lib argument since it prevents Jalview from accessing some web services, and will be disabled in future versions of Java.

Does Jalview work with nucleotide sequences and alignments?

Yes. All versions of Jalview after 2.8 (released Nov 2012) include special support for nucleic acid sequences, and employ a substitution matrix that copes with both RNA and DNA symbols to calculate trees and principal component analysis plots from alignments. Nucleotide base pair patterns provided as WUSS or VIENNA dot-bracket annotation can also be visualised, and used to calculate base-pair consensus score and sequence logos. Version 2.8 of the Jalview Desktop also includedVARNA for interactive exploration of 2D RNA structure. For the latest information about nucleic acid support, see the nucleic acid section of Jalview’s help pages.

Something that normally works in Jalview has stopped working! What should I do?

One of the commonest causes of ‘strange behaviour’ that our users have reported seems to be Jalview running out of memory. Memory errors can cause some operations to fail silently - with no warning, annotations may disappear from the alignment window, and web service calculations (apparently) never finish.

You should be able to see something in the error log - see the instructions for bug reporting on how to view this. If you do see ‘Out of memory’ or ‘Cannot allocate stack’ or ‘HeapAllocationError’ type messages, then you might be able to fix it by increasing the memory available to jalview.

How do I report a bug in Jalview?

Firstly, see if you can reproduce the bug. Check Jalview’s memory settings (Desktop->Tools->Show Memory usage) to make sure you have at least 50% memory free when testing this. If not, the problem might be because you ran out of memory when using Jalview.

Then, follow the instructions below to gather essential information regarding the bug:

• The Jalview desktop includes a Java Console - this is disabled by default, but if you enable it from the Desktop->Tools->Show Java Console menu item, a window will open that will contain the version of jalview and information about your operating system.
  • The jalview java console can slow down some operations. If it takes too long to reproduce your bug with the console open, then close it and try another way below:
• If you installed Jalview using Java Webstart, locate and start the program “javaws” or “javaws.exe” on your system. Then click the “Edit” menu, select “Preferences” then click the “Advanced” tab. Make sure you check the “Java Console” option to “Show Console”, then click “OK” and restart Jalview. A Java console will be shown when Jalview starts up, and information about any problems should be output to the console window.
• If you installed Jalview with InstallAnywhere, you will find a text file in the directory in which you installed Jalview called “output.txt” Include this file with any bug report you have.

Prepare the input data and a description of how the bug is reproduced

Prepare a copy of the alignment file you are using when you find the bug, and try to describe as fully as possible the steps you took before the bug occurred. If you can reproduce the bug with a simpler data set, then send us that instead!

Make a bug report !

If you are familiar with bug tracking systems, then you can register and submit a bug report directly to the Jalview Bug Tracker, otherwise, post a message on the Jalview Discussion Forum describing the problem, and someone will take it from there.

The old Jalview had font size and page orientation settings for its Postscript output. Where have they gone?

Jalview now exports images and graphics using the same settings as the alignment display window. Just set the font and font size, and the layout style (normal or wrapped) using the View menu.

If you do want to specify portrait or landscape, you could use the File->Print dialog box, and redirect the output to a file.

A Jalview file I created in an earlier version of Jalview no longer loads.

We have tried to ensure that all files created in earlier versions of Jalview can be read in by later versions. If you have a Jalview format file which no longer loads, please let us know by emailing the file to us. It is possible other people are having the same problem!

Jalview's Installer won't run on my Mac

Here are some symptoms we’ve observed when Jalview has failed to launch via webstart, or the Jalview installAnywhere could not be run.

In all cases, the Web start file (jnlp) and the Installer downloaded and unpacked successfully.

• Running the installer/jnlp file opens a “This program cannot be run because it comes from an unidentified developer”.
  • For some reason, your Mac has not recognised our Apple Developer Signature (if you are running Jalview 2.8.1,please tell us about this!)
  • Follow step 1, below - select the ‘Run anyway option’
• Running the installer opens a “This fileis damaged and should be moved to the trash”
  • In this case, your Mac thinks someone has tampered with the installation program, although actually, what has happened is that you’ve probably just downloaded a new version of Jalview.
  • You need to followstep 2 below - temporarily disable the security check
• Installer downloads but double clicking it does nothing.
  • This usually means that there is something wrong with your Java installation.
  1. Control-click the install-jalview package and select the “Open Package Contents” option.
  2. Double click through the directories:Contents,MacOS
  3. Double click on ‘install-jalview’ (or ‘install’, for older Jalviews)- this will open up a terminal window with some commands that executethe installer program.
  • If the installer still doesn’t launch, send us an email via jalview-discuss@jalview.org to let us know what the message is.

Changing the gatekeeper settings

First, open your system settings panel, and go to the security and privacy section:

Step 1.__If you see a prompt like the one saying ‘Open anyway’, then click it to launch the program.

Step 2.__If you don’t see a prompt like the one above, then:

• You’ll need to click the padlock so you can make changes to the security settings, and then select the ‘Anywhere’ button.
• Then try launching the installer or the application again.
• Once you’ve launched the program you can return to the gatekeeper settings and switch back to your original security settings.

My application doesn't like the "/start-end" sequence suffix in files saved by Jalview

In the application, open the preferences dialog window (Tools -> Preferences) Open the tab labelled “Output” and then select which file formats to which you do not wish to append “/start-end”

Can't see databases in Database Chooser after selecting Fetch Sequences...!

Note - this is a bug affecting an old version of Jalview - if you experience this problem with the latest version please let us know.

If you are running Jalview 2.10.0 under Ubuntu or some other (possibly GTK based) Linux desktop, you may find that after opening the Sequence Fetcher, you are presented with a dialog box just showing ‘OK’ and ‘Cancel’ buttons, but nothing much else. The empty panel is due to an underlying problem with Java, but you can still choose from the list of databases with the keyboard !

Workaround with the keyboard

There are six databases provided by default in 2.10.0: EMBL, EMBL (CDS), Ensembl, Ensembl Genomes, PDB, and Uniprot. Press the Up or Down arrow keys to select between these, and a message in the dialog box will show which database you have moved to. You can also type the first letter to jump to a particular database. Once you’ve made your selection, you’ll need to click the ‘OK’ button to proceed to that database’s fetcher dialog.

Fuzzy fonts in the alignment view on OSX Mojave (10.14.x)

On OSX Mojave, you may notice that sequences and IDs in the Jalview alignment window are hard to read. To fix this, first:

1. Save your work and shut down Jalview

2. Open a Terminal window (use spotlight or the Launcher and type ‘Terminal’ to locate the Terminal App), and type:

defaults write -g CGFontRenderingFontSmoothingDisabled -bool NO

3. Start Jalview again and load an alignment to check that the fonts are now legible.

Thanks to Marcin for reporting this issue and testing the workaround via issues.jalview.org/browse/JAL-3134

Jalview's menus and fonts are too small on my Windows machine !

When Jalview is run on Windows machines with high resolution displays (e.g. 4K, retina, etc) resolution screens, you might find that all the menus, window titles, and alignment data are really tiny. That’s because on high-resolution displays, all the windows and fonts have to be magnified so that you can read them, and the fix is to ask Windows to do the same for the Jalview application.

Instructions on how to do this can be found in several places on the ’net.

Your milage may vary so please let us know if you are having problems via the jalview-discuss AT jalview.org mailing list!

See https://pivotce.com/2017/12/11/fix-java-applications-for-high-dpi-display/ for the following solution which should work for launching Jalview via webstart on machines with Java 8 installed.

1. Close Jalview
2. Find java.exe and/or javaw.exe

• for pre 2.11.0 likely found in C:\Program Files\Java\jre(version#)\bin
• for 2.11.0 and later this can be found in %APPDATA%\Local\Jalview\jre\bin

3. Right click on it and select -> Properties
4. Go to Compatibility tab
5. Check Override high DPI scaling behavior.
6. Choose System for Scaling performed by:
7. Click OK
8. Relaunch Jalview

Jalview has encountered an error during launch

If you’ve been redirected to this FAQ then it probably means that the Jalview Native application has encountered an error whilst trying to start. Here are some tips for various problems:

Problems on Windows:

If your installation of Jalview goes fine, but double clicking on the Jalview icon does not produce any error message, window or any other activity (other than the spinning blue circle) this might be caused by a space character in Jalview’s installation folder. To fix this:

1. Uninstall the non-working Jalview by either: * Open the Control Panel and go to Programs→Programs and Features→Uninstall a program. Select Jalview 2.11.1.0 from the program list and then click on the Uninstall/Change button above the list. This will launch Jalview’s uninstall wizard, follow the instructions. * Open a File Explorer and go to location %APPDATA%\Local\Jalview\uninstall.exe or %LOCALAPPDATA%\Local\Jalview\uninstall.exe if the first one isn’t found. This should launch Jalview’s uninstall wizard, follow the instructions.
2. Install Jalview again using the same installer as before, but this time on the second screen (Select Destination Directory) ensure the path has no spaces (e.g. type in C:\Jalview)

Problems on linux:

1. If you have used the Jalview-X_unix_installer_x_x_x-j8.sh installer, or the similar *-j8.tar.gz distribution, in some cicumstances you might get an error when launching Jalview that includes the message “Failed to rename ./jre.tgz_new to ./jre.tgz”:

This (slightly misleading) error message is caused by the launcher not being able to find the right version of the Java runtime environment (JRE).

For Jalview 2.11.1.0 or later we distribute an installer for linux with 64bit intel processors that bundles a JRE, we recommend using this installer to upgrade. For other linux platforms please read below.

In the case of Jalview 2.11.0 this should be Java 1.8. You can fix this by installing the right version of Java either with your distribution’s package manager. e.g.

On Ubuntu 18.04:

sudo apt install openjdk-8-jre

On CentOS 8 or Fedora 31:

sudo yum install java-1.8.0-openjdk

or you can install a local version of the Java runtime environment – we recommend the installers from AdoptOpenJDK.

If after installing a Java 1.8 runtime environment you are experiencing the same problem, you may need to tell the Jalview launcher where to find the JRE 1.8 with the environment variable INSTALL4J_JAVA_HOME_OVERRIDE. You can achieve this on the command line with, e.g. (assuming you installed Jalview in the default location ~/opt/Jalview)

On Ubuntu 18.04,

INSTALL4J_JAVA_HOME_OVERRIDE=/usr/lib/jvm/java-8-openjdk-amd64 ~/opt/Jalview/Jalview

On CentOS 8 or Fedora 31

INSTALL4J_JAVA_HOME_OVERRIDE=/usr/lib/jvm/jre-1.8.0 ~/opt/Jalview/Jalview

Alternatively you could add an “export INSTALL4J_JAVA_HOME_OVERRIDE=…” in your ~/.bashrc file but this could affect other applications installed using install4j.

Jalview will use a Java 11 runtime environment in version 2.12.

2. If you have the openjdk-8-jre-headless package installed but NOT the openjdk-8-jre package (for example this might be default on an Ubuntu Server distribution) then you might find Jalview silently fails to launch and the ~/opt/Jalview/launcher.log file contains:

Exception in thread "Getdown" java.awt.AWTError: Assistive Technology not found: org.GNOME.Accessibility.AtkWrapper

To fix this you can either install openjdk-8-java with

sudo apt install openjdk-8-java

or comment out the following line “assistive_technologies=org.GNOME.Accessibility.AtkWrapper” in the file /etc/java-8-openjdk/accessibility.properties. You can do this with

sudo sed -i -E 's/^(assistive_technologies=org\.GNOME\.Accessibility\.AtkWrapper)/#\1/' /etc/java-8-openjdk/accessibility.properties

Other problems:

Depending on your platform you will need to take a look at the launcher.log file within the Jalview installation directory:

• On Windows the Jalview installation directory defaults to %APPDATA%\Local\Jalview,
• On Linux/Unix the Jalview installation directory defaults to ~/opt/Jalview,
• On macOS the launcher.log file can be found in /Applications/Jalview.app/Contents/Resources/app. To get here in Finder right click on the Jalview icon in Applications and select “Show Package Contents”. You can then click through to Contents → Resources→ app . Warning! Editing or deleting files in the Jalview.app package might result in your Jalview installation breaking!

Jalview's Menus and Fonts are too small on my Linux machine

If you are running Jalview in Linux with a HiDPI or 4K monitor then the font size and menus are likely to be too small to be practical.

UPDATE: Jalview 2.11.1.1 and above should automatically detect a Linux HiDPI display, and scale the application appropriately if you are using the Java 11 version. You can download a newer installer from https://www.jalview.org/getdown/release/install4j/11/jalview-2_11_1_1-linux_x64-java_11.sh (coming soon!).

A previously installed version of the Java 11 version of Jalview should update automatically and will apply the HiDPI scaling the NEXT time it is launched after it auto-updates.

Please note that we have found a “drag-and-drop” positional error in the underlying Java components when using upscaling in Linux. This is detailed below.

ORIGINAL: To effectively remedy this, you will need a Java 11 version of Jalview. For Jalview 2.11.1.0 Java 11 is not officially supported but we are working towards that, so you can:

1. Download a Java 11 linux installer from https://www.jalview.org/getdown/release/install4j/11/jalview-2_11_1_0-linux_x64-java_11.sh
   (if you are using linux a platform other than intel 64 bit you will need to obtain a Java 11 JRE, e.g. from https://adoptopenjdk.net/, and then download the non-bundled-jre unix installer from [https://www.jalview.org/getdown/release/install4j/11/jalview-2_11_1_0-unix- java_11.sh](https://www.jalview.org/getdown/release/install4j/11/jalview- 2_11_1_0-unix-java_11.sh)).

2. Install as usual with the command

bash jalview-2_11_1_0-linux_x64-java_11.sh

3. Assuming this installed into the directory ~/opt/jalview, edit the file ~/opt/jalview/jalview and add onto the first blank line **export GDK_SCALE=2** so that the top of that file looks like

#!/bin/sh
export GDK_SCALE=2

# Uncomment the following line to override the JVM search sequence
# INSTALL4J_JAVA_HOME_OVERRIDE=
# Uncomment the following line to add additional VM parameters
# INSTALL4J_ADD_VM_PARAMS=
...

Jalview should now run at double sized resolution.

DRAG-AND-DROP ISSUE: When running Jalview (or any Java Swing application) with a scaling larger than 1 (most likely 2), the positional calculation when a drag-and-drop event occurs appears to be incorrect. This is most obvious when, for instance, dragging an alignment file from your file manager application onto Jalview when you have an existing alignment window open. If you drop the file over the existing alignment, the new file should be appended to the existing alignment. If you drop the file over Jalview but not over an existing alignment it should open in a new alignment window. Because the drop event’s position is miscalculated the results can be unexpected. See the issue JAL-3702 for more details.

For consistent behaviour, use the Jalview menu File→Input Alignment→From File to open a new alignment window. To append to an existing alignment window use that alignment window’s File→Add Sequences→From File option.

Fonts look incorrectly sized in Ubuntu Linux

If you are running Jalview in Ubuntu Linux and think that fonts look incorrectly sized, like the following screenshot,

you can turn off the Ubuntu system default (for Java swing applications) Gtk “Look and Feel” by running Jalview with the environment variable JAVA_TOOL_OPTIONS by running Jalview with the following command:

JAVA_TOOL_OPTIONS="-Dswing.systemlaf=javax.swing.plaf.metal.MetalLookAndFeel" ~/opt/jalview/jalview

To make this option always apply you can edit the file

~/opt/jalview/jalview

(or the script “jalview” in the directory you installed Jalview into) and add the following to the as the second or third line:

export JAVA_TOOL_OPTIONS="-Dswing.systemlaf=javax.swing.plaf.metal.MetalLookAndFeel"

so that the top of the script should look like:

#!/bin/sh

export JAVA_TOOL_OPTIONS="-Dswing.systemlaf=javax.swing.plaf.metal.MetalLookAndFeel"

# Uncomment the following line to override the JVM search sequence
# INSTALL4J_JAVA_HOME_OVERRIDE=
# Uncomment the following line to add additional VM parameters
# INSTALL4J_ADD_VM_PARAMS=

Note that if you are also having problems with the Jalview interface appearing too small on a high resolution (HiDPI or 4K) monitor then also see the FAQ Jalview’s Menus and Fonts are too small on my Linux machine

How do I set web proxy settings for Jalview's auto-updater and web services?

Jalview uses a launcher (called getdown, see https://github.com/threerings/getdown) that runs an auto-updater for Jalview and verifies Jalview files by checking the Jalview web site. Whilst the launcher checks for existing system proxy settings, sometimes it does not find those settings. In this case it may pop up a window asking for proxy settings. If this does not happen, and proxy settings are required, you can create a file called

proxy.txt

that should contain your proxy host and port like this:

host=your.proxyhost.com
port=3128

You should put the file in the same folder as the file getdown.txt:

• In Windows this is the folder you installed Jalview into (by default this is %APPDATA%\Local\Jalview)
• In macOS this is buried in the Jalview application bundle as Contents/Resources/app (by default /Applications/Jalview.app/Contents/Resources/app/)
• In Linux this is also the folder you installed Jalview into (by default this is ~/opt/jalview/).

The current release (2.11.1.0) does not pass settings from this file on to the Jalview application. This will be fixed in a future release. In the meantime you can configure the proxy for Jalview in Jalview’s own Preferences (see Tools->Preferences->Connections).

Jalview failed to launch, displaying an error saying it was "unable to download the necessary files"

If you have a problem launching Jalview that results in an error message on the splash screen reading:

“We were unable to download the necessary files after five attempts. You can try running the application again, but if it fails you may need to uninstall and reinstall.”

Like this screenshot:

Then you should close the splash screen window and try and launch the Jalview application again.

If this does not work, you should install the latest Jalview release (found at https://www.jalview.org/getdown/release/). The latest installer can be installed on top of the old version.

Can Jalview run with Java 9+

Jalview is compatible with Java 11 and later, but only if you have downloaded and installed a Java 11 compatible Jalview distribution. For now, our recommended distributions run Jalview under Java 8.

If you have installed Jalview via InstallAnywhere and you cannot access JABAWS services (a dialog box appears after you start Jalview about this), then you can patch the Jalview installation.

On OSX: - Add two lines to the Jalview.app/Contents/Info.plist file after the line starting -Xdock:icon=

<string>--add-modules=java.se.ee</string>
<string>--illegal-access=warn</string>

On Windows: Open the Jalview.lax file in Notepad (or another editor) # and locate and replace the existing lax.nl.java.option.additional line with

lax.nl.java.option.additional=--add-modules=java.se.ee --illegal-access=warn

Launching Jalview from the command line on Java 9

To run Jalview 2.10.3 on Java 9, you need to add two additional JVM command line arguments:

--add-modules=java.se.ee --illegal-access=warn

Java 9 also ignores the ‘java.ext.dirs’ property so instead we recommend launching jalview via a script like:

# set install path of jalview
JALVIEWDIR=$DIR;  # change $DIR to where you built Jalview
# compile the classpath
CLASSPATH=`echo $JALVIEWDIR/*.jar | sed -e 's/r /r:/g'`
# launch Jalview
#you might also want --Xmx<memory in GB>G
java -classpath $CLASSPATH --add-modules=java.se.ee --illegal-access=warn jalview.bin.Jalview ${@};

I downloaded the Jalview Installer for OSX but the install application won't run

The OSX InstallAnywhere version of Jalview is downloaded as a ZIP archive (install.zip) which is normally unpacked automatically to create an application called ‘install’ that you can run. If nothing happens when you double click the application, then there are a few things that could go wrong.

Installer doesn’t launch because it was unpacked with a third-party archive tool

If you have chosen an alternative archive program for OSX to use to unpack ZIP files, then it probably didn’t set the executable permissions for the application after it unpacked it. Theeasiest solution is to right or option click the install.zip that you downloaded, and choose ‘Open with -> Archive Utility (10.X)’ (where X is the numeric version of OSX that you are running); this will create a new ‘install’ application (probably called ‘install 2’) that you can now launch.

If using a different archiver doesn’t work, or you are working from the console, then you need to delve into the installer’s application directory. Open the console, cdto the directory where the install application is located (probably ~/Downloads), and type:

chmod u+x install.app/Contents/MacOS/install
open install.app

Permissions problems result in an error shown in the OSX Console window that reads something like

([0x0-0x6a86a8].install[25620])
posix_spawn("/Users/jimp/install.app/Contents/MacOS/install", ...): Permission
denied

If you see anything else, paste it into the search box on http://issues.jalview.org to see if it has been reported.

Related bugs in the Jalview Issue Database:JAL-746.

I'm having problems using InstallAnywhere on Mac OSX 10.3.9

There is a Mac OS X bug that affects InstallAnywhere LaunchAnywheres on OS X 10.3.9 systems with the QuickTime 7.0.4 upgrade.

This appears to only affect systems running 10.3.9, and not 10.4. The current workaround is to revert to QuickTime 7.0.1, through a reinstaller available from Apple on the Support/Downloads page.

http://www.apple.com/support/downloads/quicktime701reinstallerforquicktime704.html

Is there a quick reference for Jalview?

Yes, a quick reference PDF for an early release of Jalview 2 is here, but we haven’t updated it for a while.