Use the latest version of Circos and read Circos best practices—these list recent important changes and identify sources of common problems.
If you are having trouble, post your issue to the Circos Google Group and include all files and detailed error logs. Please do not email me directly unless it is urgent—you are much more likely to receive a timely reply from the group.
Don't know what question to ask? Read Points of View: Visualizing Biological Data by Bang Wong, myself and invited authors from the Points of View series.
If you are having trouble with installation of Perl or modules, use online resources that explain the details of how to download Perl, get it working (Linux, Mac OS X, Windows [win32.perl.org wiki, ActiveState, Strawberry]), and how to install modules (UNIX, Windows). If you're still stuck, post your questions to the Circos group.
Having trouble with libgd and GD? See the Perl Monks libgd/GD Tutorial, Shaun Jackman's Homebrew formula, Paulo Nuin's Installing Circos on Mac OS X, Wang's install zlib/libpng/jpeg/freetype/libgd/GD on Mavericks as well as my own guide for installation of libpng, freetype, libgd and GD on Mac OS X Mavericks. There are some useful threads in the Google Group about this.
Stumped by an error? A good strategy is to Google the error message (e.g. mkdir /usr/local/share/man: permission denied) to find the solution.
Want to learn more about Perl? Try learn.perl.org.
To run Circos, you need Perl. Perl is an interpreted language, which means that you do not need to compile Circos to run it. The code is read in by the Perl executable, which takes care of interpreting, compiling and running it. To install Circos, nothing other than unpacking the archive is required.
For an overview of the installation process, and how it differs between UNIX and Windows, please also refer to the UNIX vs Windows section.
First, download Circos. The contents of the distribution are described below.
You don't need to move or edit any files in the main distribution.
Assuming that you want to install in
> cd ~ > mkdir software > mkdir software/circos > cd software/circos # download Circos and place the archive in the directory > ls -rw-r--r-- 1 martink users 26725778 Jun 6 11:04 circos-0.67-pre4.tgz # unpack > tar xvfz circos-0.67-pre4.tgz ... circos-0.67-pre4/data/karyotype/karyotype.arabidopsis.txt circos-0.67-pre4/data/karyotype/karyotype.zeamays.txt circos-0.67-pre4/data/karyotype/karyotype.oryzasativa.txt # make a symlink to current > ln -s circos-0.67-pre4 current > ls drwxr-xr-x 10 martink users 4096 Jun 6 11:06 circos-0.67-pre4/ -rw-r--r-- 1 martink users 26725778 Jun 6 11:04 circos-0.67-pre4.tgz lrwxrwxrwx 1 martink users 16 Jun 6 11:07 current -> circos-0.67-pre4/ # delete the tarball, if you want
To install GD and Perl modules on Ubuntu, use
sudo apt-get -y install libgd2-xpm-dev
If you're using Homebrew, you can use Shaun Jackman's formula
brew tap homebrew/science brew remove gd brew install gd --with-freetype brew install cpanminus sudo chown "$USER":admin /Library/Perl/5.16 # on Mac OS cpanm Config::General Font::TTF::Font Math::Bezier Math::VecStat Readonly Set::IntSpan Text::Format cpanm --force GD::Polyline brew install circos brew test circos
Windows users should use Windows' built-in handling of
.tgz files (in Windows Vista or newer). The
.tgz extension is a short version of
.tar.gz, which more explicitly indicates that the file is a
tar archive which has been subsequently compressed with
If you are unfamiliar with the Windows DOS command line, these tutorials should help.
Circos uses command-line flags, which are required. In the very least, you need to specify the image configuration file using
These flags in described in the Runtime Parameters tutorial.
It's a good idea to add the
bin/ directory in the distribution to your
PATH so that you can run
bin/circos from anywhere.
Assuming you have Circos in
ROOT=~/software/circos/current as described above, append this to your
You'll need to explicitly execute either
~/.bash_profile for this to take effect
> . ~/.bashrc # or > . ~/.bash_profile
Finally, test that your
PATH has been modified,
> cd ~ > echo $PATH ~/software/circos/current/bin: ... > which circos ~/software/circos/current/bin/circos
To run Circos, you'll need to invoke perl and pass the Circos script as an argument, along with any command-line parameters
C:>perl C:\path\to\circos\bin\circos [any command-line parameters]
Documentation uses UNIX paths and commands. On Windows, if you see instruction to run a script, such as
> tools/bin/binlinks ...
interpret it as
C:>perl tools\bin\binlinks ...
Also note that on UNIX file paths use
/ as a separation (e.g.
/bin/env) and on Windows
\ is used (e.g.
References to command-line commands like
cat are specific to UNIX. It should be clear what is being attempted, such as reporting the current working directory (
echo %cd% on Windows) or listing a file (
echo on Windows).
Check whether you have any missing modules
> pwd ~/software/circos/current > bin/circos -modules ok 1.26 Carp ok 0.37 Clone ok 2.50 Config::General ok 3.33 Cwd ok 2.145 Data::Dumper ...
If any modules missing, refer to Perl Modules tutorial for details about installing them.
/bin/env: no such file or directory
On UNIX, if you see an error like this when you try to run Circos
-bash: /bin/env: No such file or directory
then the location of the
env binary on your system is not
/bin/env. For example, on Mac OS X
env is in
First check where your
env binary is
> which env /usr/bin/env
Now either change the first line in
or (better) make a symlink from
> sudo su > cd /bin > ln -s /usr/bin/env env
You should get a man page. On the other hand, if you get an error like
If you don't yet have any data to use, you can play with running Circos using the example data set, included in the distribution. The commands below are for UNIX systems—for Windows, see
> cd example # run.out will contain debug report # image files are circos.png and circos.svg > ./run # explicitly specify configuration file > ../bin/circos -conf etc/circos.conf # with more debugging > ../bin/circos -conf etc/circos.conf -debug_group summary,io,timer # with all debugging > ../bin/circos -conf etc/circos.conf -debug_group _all # silently > ../bin/circos -conf etc/circos.conf -silent
When you download and unpack Circos, you'll have a directory structure as follows
circos-x.xx CHANGES README TODO bin/ etc/ fonts/ lib/ tiles/ tools/
Tutorials are available separately and provide the files in
The Circos script is located in this directory. Circos is written
in Perl and is comprised of a single executable file
The distribution includes a large number of data files that are required by the tutorials. Most of these data files are parsed versions of output of the UCSC Genome Viewer Table Browser. A few of the data files contain randomly generated data.
Circos global configuration files live here, such as
fonts.conf. These files are imported into other configuration
files (e.g. tutorial configuration files).
The contents of the color and font files are described in the Configuration File section.
Tutorial configuration files are located in
TrueType (TTF) fonts used by Circos. These fonts are defined in
etc/fonts.conf. Circos supports only TTF fonts (not Postscript or OTF).
Code libraries. You don't need to look.
Tiles for pattern fills.
Various helper tools for Circos to manipulate (e.g. count links with
tools/binlinks) and parse (e.g. tabular visualization using
Tutorials are available separately and are the documentation
for Circos. Each tutorial has an associated image and configuration
Tutorials are organized into groups and sections. Each group illustrates a feature set of Circos, and individual sections illustrate the configuration syntax for specific aspects of the feature set.
tutorials/ ... 2/ 1/ 2/ circos.conf ticks.conf ideogram.conf 3/ ... ...
All of the tutorial configuration files will import global
configuration files from
etc/, such as