Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
doc Tutorial.rd.html is regenerated by rake retutorial2html Sep 17, 2015
etc/bioinformatics New default etc/bioinformatics/seqdatabase.ini Aug 17, 2012
gemfiles Gemfile for local development. Nov 29, 2016
lib update TogoWS documentation. genbank -> ncbi-nucleotide Oct 18, 2018
sample update TogoWS documentation. genbank -> ncbi-nucleotide Oct 18, 2018
test construct ambiguity nucleotide to amino acid table Jun 2, 2018
.travis.yml Gemfile for local development. Nov 29, 2016
BSDL BSDL is referred in COPYING and COPYING.ja Jun 30, 2015
COPYING changes of Ruby's License is reflected. Jun 30, 2015
COPYING.ja changes of Ruby's License is reflected. Jun 30, 2015
ChangeLog ChangeLog since 1.5.0 release Jul 2, 2015
GPL License files are added. Aug 18, 2009
Gemfile Gemfile for local development. Nov 29, 2016
KNOWN_ISSUES.rdoc KNOWN_ISSUES.rdoc: remove descriptions about Bio::SQL Jun 17, 2016
LEGAL License files are added. Aug 18, 2009
LGPL License files are added. Aug 18, 2009
README.rdoc README.rdoc: about bioruby-phyloxml and bio-biosql Jun 17, 2016
README_DEV.rdoc README_DEV.rdoc: added git tips and policies, etc. Sep 13, 2011
RELEASE_NOTES.rdoc Incompatible change about deprecated Bio::Taxonomy is described. Sep 15, 2015
Rakefile Test bug: fix gem version mismatch error on Travis-CI Jun 7, 2016
appveyor.yml appveyor.yml: eliminate old Ruby versions and add Ruby 2.3 Jun 8, 2016
bioruby.gemspec Remove settings about executables Sep 15, 2017
bioruby.gemspec.erb Remove settings about executables Sep 15, 2017
setup.rb remove duplicated line and suppress Ruby 2.2 warning Mar 21, 2015


README.rdoc - README for BioRuby


Copyright (C) 2001-2007 Toshiaki Katayama <>, Copyright (C) 2008 Jan Aerts <> Copyright (C) 2011-2015 Naohisa Goto <>


The Ruby License

  • The above statement is limited to this file. See below about BioRuby's copyright and license.



Copyright (C) 2001-2012 Toshiaki Katayama <>

BioRuby is an open source Ruby library for developing bioinformatics software. Object oriented scripting language Ruby has many features suitable for bioinformatics research, for example, clear syntax to express complex objects, regular expressions for text handling as powerful as Perl's, a wide variety of libraries including web service etc. As the syntax of the Ruby language is simple and very clean, we believe that it is easy to learn for beginners, easy to use for biologists, and also powerful enough for the software developers.

In BioRuby, you can retrieve biological database entries from flat files, internet web servers and local relational databases. These database entries can be parsed to extract information you need. Biological sequences can be treated with the fulfilling methods of the Ruby's String class and with regular expressions. Daily tools like Blast, Fasta, Hmmer and many other software packages for biological analysis can be executed within the BioRuby script, and the results can be fully parsed to extract the portion you need. BioRuby supports major biological database formats and provides many ways for accessing them through flatfile indexing, web services etc. Various web services can be easily utilized by BioRuby.


See RELEASE_NOTES.rdoc for news and important changes in this version.

Documents in this distribution

Release notes, important changes and issues


This file. General information and installation procedure.


News and important changes in this release.


Known issues and bugs in BioRuby.


News and incompatible changes from 1.4.2 to 1.4.3.


News and incompatible changes from 1.4.1 to 1.4.2.


News and incompatible changes from 1.4.0 to 1.4.1.


News and incompatible changes from 1.3.1 to 1.4.0.


News and incompatible changes from 1.2.1 to 1.3.0.


News and incompatible changes from 0.6.4 to 1.2.1.

Tutorials and other useful information


BioRuby Tutorial.


HTML version of Tutorial.rd.

BioRuby development


History of changes.


changes from 1.4.2 to 1.4.3.


changes before 1.4.2.


changes before 1.3.1.


Describes ways to contribute to the BioRuby project, including coding styles and documentation guidelines.

Documents written in Japanese


BioRuby Tutorial written in Japanese.


HTML version of Tutorial.rd.ja.

Sample codes

In sample/, There are many sample codes and demo scripts.


BioRuby's official website is at You will find links to related resources including downloads, mailing lists, Wiki documentation etc. in the top page.

Mirror site is available, hosted on Open Bioinformatics Foundation (OBF).



The stable release is freely available from the BioRuby website.


RubyGems (packaging system for Ruby) version of the BioRuby package is also available for easy installation.


If you need the latest development version, this is provided at

and can be obtained by the following procedure:

% git clone git://


  • Ruby 1.8.7 or later (except Ruby 1.9.0) –

    • Ruby 2.1.6 or later, or Ruby 2.2.2 or later is recommended.

    • This is the final version running on Ruby 1.8, tested with Ruby1.8.7-p374.

    • See KNOWN_ISSUES.rdoc for Ruby version specific problems.


Some optional libraries can be utilized to extend BioRuby's functionality. If your needs meets the following conditions, install them by using RubyGems, or download and install from the following web sites.

For faster parsing of the BLAST XML output format:

Creating faster flatfile index using Berkley DB:


INSTALL by using RubyGems (recommended)

If you are using RubyGems, just type

% gem install bio

Alternatively, manually download bio-X.X.X.gem from and install it by using gems command.

RubyGems is bundled with Ruby 1.9.1 or later. For Ruby 1.8.7 or earlier, download and install RubyGems from .

INSTALL without RubyGems

In the bioruby source directory (such as bioruby-x.x.x/), run setup.rb as follows:

% su
# ruby setup.rb

These simple step installs this program under the default location of Ruby libraries. You can also install files into your favorite directory by supplying setup.rb some options. Try “ruby setup.rb –help”.

If your operating system supports 'sudo' command (such as Mac OS X), try the following procedure instead of the above.

% sudo ruby setup.rb

For older version users: “install.rb” is now renamed to “setup.rb”. The options “config”, “setup”, and “install” are still available.

% ruby setup.rb config
% ruby setup.rb setup
% su
# ruby setup.rb install

You can run

% ruby setup.rb --help

for more details.

Running self-test

To check if bioruby works fine on a machine, self-test codes are bundled. Note that some tests may need internet connection.

To run tests,

% ruby test/runner.rb

If you are using Ruby 1.8.x and you want to use components installed by using RubyGems, explicit loading of RubyGems may be needed.

% ruby -rubygems test/runner.rb

Alternatively, testrb, the test runner command of ruby, can be used.

% testrb test/

With testrb, you can select tests to run, for example,

% testrb test/unit

For those familiar with Rake,

% rake test

also works.

Before reporting test failure, please check KNOWN_ISSUES.rdoc about known platform-dependent issues. We are happy if you write patches to solve the issues.


If you want to use the OBDA (Open Bio Database Access) to obtain database entries, copy a sample configuration file in the BioRuby distribution



/etc/bioinformatics/seqdatabase.ini	(system wide configuration)


~/.bioinformatics/seqdatabase.ini	(personal configuration)

and change the contents according to your preference. For more information on the OBDA, see .


You can load all BioRuby classes just by requiring 'bio.rb'. All the BioRuby classes and modules are located under the module name 'Bio' to separate the name space.

#!/usr/bin/env ruby
require 'bio'

You can also read other documentation in the 'doc' directory.


RubyGems on Ruby 1.8.x

With RubyGems on Ruby 1.8.x, you may need to load 'rubygems' library before using 'bio'. This may not be needed, depending on settings of Ruby.

#!/usr/bin/env ruby
require 'rubygems'
require 'bio'

PLUGIN (Biogem)

Many plugins (called Biogem) are now available. See for list of plugins and related software utilizing BioRuby.

Plugins (Biogems) listed below had been included in BioRuby in former days, and were split to separate packages to reduce complexity and external dependencies.

  • bioruby-phyloxml

    • NOTE: Please uninstall bio-phyloxml, that have been created as a preliminary trial of splitting a module in 2012 and have not been maintained after that.

  • bio-biosql

To develop your own plugin, see “Plugins” pages of BioRuby Wiki.


BioRuby can be freely distributed under the same terms as Ruby. See the file COPYING (or COPYING.ja written in Japanese).

As written in the file COPYING, see the file LEGAL for files distributed under different license. For example, setup.rb which comes from “setup” developed by Minero Aoki ( is licensed under LGPL 2.1.


If you use BioRuby in academic research, please consider citing the following publication.

  • BioRuby: Bioinformatics software for the Ruby programming language. Naohisa Goto, Pjotr Prins, Mitsuteru Nakao, Raoul Bonnal, Jan Aerts and Toshiaki Katayama. Bioinformatics (2010) 26(20): 2617-2619.


Current staff of the BioRuby project can be reached by sending e-mail to <>.