Circos > Documentation > Tutorials > Configuration > Installation
Circos at the EMBO NGS workshop in Tunis, Sept 15–25.

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.

0 — Configuration and Installation

2. Distribution and Installation

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 [ wiki, ActiveState, Strawberry]), and how to install modules (UNIX, Windows). If you're still stuck, post your questions to the Circos group.

Need to install modules? See A Guide to Installing Modules and its corresponding tutorial for Windows users.

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.

Need to run Bash shell batch files in Windows? You'll need to install a UNIX command line shell, like Cygwin.

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

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.

Installing Circos

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.

Installing Circos on UNIX

Assuming that you want to install in ROOT=~/software/circos,

> 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
# 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 apt-get.

sudo apt-get -y install libgd2-xpm-dev

Installing Circos on Mac

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

Installing Circos on Windows

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 gzip.

You can unpack the archive with 3rd party utilities like the free 7-Zip, or the venerable (but not free) WinZip.

If you are unfamiliar with the Windows DOS command line, these tutorials should help.

Running Circos

Circos uses command-line flags, which are required. In the very least, you need to specify the image configuration file using -conf.

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 ~/.bashrc or ~/.bash_profile.

export PATH=~/software/circos/current/bin:$PATH

You'll need to explicitly execute either ~/.bashrc or ~/.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


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. C:\perl\bin\perl).

References to command-line commands like pwd and 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).

checking for missing perl modules

Check whether you have any missing modules

> pwd
> 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

missing modules?

If any modules missing, refer to Perl Modules tutorial for details about installing them.

On Windows, both Strawberry Perl and ActiveState Perl have package managers that help you install, update and remove modules.

/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 /bin/usr/env.

First check where your env binary is

> which env

Now either change the first line in bin/circos and tools/*/bin to

#!/usr/bin/env perl

or (better) make a symlink from /usr/bin/env to /bin/env

> 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

using the example data set

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 README.

> 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

Contents of Circos Distribution

When you download and unpack Circos, you'll have a directory structure as follows


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 bin/circos.


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 housekeeping.conf, colors.conf and 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 tutorials/ (see below).


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 tools/tableviewer) data.


Tutorials are available separately and are the documentation for Circos. Each tutorial has an associated image and configuration s.

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.


All of the tutorial configuration files will import global configuration files from etc/, such as housekeeping.conf and colors_fonts_patterns.conf.