Repository files navigation

The Biopython Project is an international association of developers of freelyavailable Python tools for computational molecular biology.

This README file is intended primarily for people interested in workingwith the Biopython source code, either one of the releases from thehttps://biopython.org website, or from our repository on GitHubhttps://github.com/biopython/biopython

Our user-centric documentation,The Biopython Tutorial and Cookbook, and APIdocumentation, is generated from ourrepository using Sphinx.

TheNEWSfile summarises the changes in each release of Biopython, alongside theDEPRECATEDfile which notes API breakages.

The Biopython package is open source software made available under generousterms. Please see theLICENSE file forfurther details.

If you use Biopython in work contributing to a scientific publication, we askthat you cite our application note (below) or one of the module specificpublications (listed on our website):

Cock, P.J.A. et al. Biopython: freely available Python tools for computationalmolecular biology and bioinformatics. Bioinformatics 2009 Jun 1; 25(11) 1422-3https://doi.org/10.1093/bioinformatics/btp163 pmid:19304878

Python includes the package management system "pip" which should allow you toinstall Biopython (and its dependency NumPy if needed), upgrade or uninstallwith just one terminal command:

pip install biopythonpip install --upgrade biopythonpip uninstall biopython

Since Biopython 1.70 we have provided pre-compiled binary wheel packages onPyPI for Linux, macOS and Windows. This means pip install should be quick,and not require a compiler.

As a developer or potential contributor, you may wish to download, build andinstall Biopython yourself. This is described below.

We currently recommend using Python 3.13 fromhttps://www.python.org

Biopython is currently supported and tested on the following Pythonimplementations:

• Python 3.10, 3.11, 3.12, 3.13 and 3.14 -- seehttps://www.python.org
• PyPy3.10 v7.3.17 -- or later, seehttps://www.pypy.org

Biopython requires NumPy (seehttps://www.numpy.org) which will be installedautomatically if you install Biopython with pip (see below for compilingBiopython yourself).

Depending on which parts of Biopython you plan to use, there are a number ofother optional Python dependencies, which can be installed later if needed:

• ReportLab, seehttps://www.reportlab.com/opensource/ (optional)This package is only used inBio.Graphics, so if you do not need thisfunctionality, you will not need to install this package.
• matplotlib, seehttps://matplotlib.org/ (optional)Bio.Phylo uses this package to plot phylogenetic trees.
• networkx, seehttps://networkx.github.io/ (optional) andpygraphviz or pydot, seehttps://pygraphviz.github.io/ andhttps://code.google.com/p/pydot/ (optional)These packages are used for certain niche functions inBio.Phylo.
• rdflib, seehttps://github.com/RDFLib/rdflib (optional)This package is used in the CDAO parser underBio.Phylo.
• psycopg2, seehttps://initd.org/psycopg/ (optional) orPyGreSQL (pgdb), seehttps://www.pygresql.org/ (optional)These packages are used byBioSQL to access a PostgreSQL database.
• MySQL Connector/Python, seehttps://dev.mysql.com/downloads/connector/python/This package is used byBioSQL to access a MySQL database, and issupported on PyPy too.
• mysqlclient, seehttps://github.com/PyMySQL/mysqlclient-python (optional)This is a fork of the older MySQLdb and is used byBioSQL to access aMySQL database. It is supported by PyPy.

In addition there are a number of useful third party tools you may wish toinstall such as standalone NCBI BLAST, EMBOSS or ClustalW.

We recommend using the pre-compiled binary wheels available on PyPI using:

pip install biopython

However, if you need to compile Biopython yourself, the following are requiredat compile time:

• Python including development header files likepython.h, which on Linuxare often not installed by default (trying looking for and installing apackage namedpython-dev orpython-devel as well as thepythonpackage).

• Appropriate C compiler for your version of Python, for example GCC on Linux,MSVC on Windows. For Mac OS X, or as it is now branded, macOS, use Apple'scommand line tools, which can be installed with the terminal command:

  xcode-select --install

  This will offer to install Apple's XCode development suite - you can, but itis not needed and takes a lot of disk space.

Then either download and decompress our source code, or fetch it using git.Now change directory to the Biopython source code folder and run:

pip install -e .python setup.py testsudo python setup.py install

Substitutepython with your specific version if required, for examplepython3, orpypy3.

To exclude tests that require an internet connection (and which may take along time), use the--offline option:

python setup.py test --offline

If you need to do additional configuration, e.g. changing the installdirectory prefix, please typepython setup.py.

Biopython includes a suite of regression tests to check if everything isrunning correctly. To run the tests, go to the biopython source codedirectory and type:

pip install -e .python setup.py test

If you want to skip the online tests (which is recommended when doing repeatedtesting), use:

python setup.py test --offline

Do not panic if you see messages warning of skipped tests:

test_DocSQL ... skipping. Install MySQLdb if you want to use Bio.DocSQL.

This most likely means that a package is not installed. You canignore this if it occurs in the tests for a module that you were notplanning on using. If you did want to use that module, please installthe required dependency and re-run the tests.

Some of the tests may fail due to network issues, this is often down tochance or a service outage. If the problem does not go away onre-running the tests, you can use the--offline option.

There is more testing information in the Biopython Tutorial & Cookbook.

Biopython 1.61 introduced a new warning,Bio.BiopythonExperimentalWarning,which is used to mark any experimental code included in the otherwisestable Biopython releases. Such 'beta' level code is ready for widertesting, but still likely to change, and should only be tried by earlyadopters in order to give feedback via the biopython-dev mailing list.

We'd expect such experimental code to reach stable status within one or tworeleases, at which point our normal policies about trying to preservebackwards compatibility would apply.

While we try to ship a robust package, bugs inevitably pop up. If you arehaving problems that might be caused by a bug in Biopython, it is possiblethat it has already been identified. Update to the latest release if you arenot using it already, and retry. If the problem persists, please search ourbug database and our mailing lists to see if it has already been reported(and hopefully fixed), and if not please do report the bug. We can't fixproblems we don't know about ;)

Issue tracker:https://github.com/biopython/biopython/issues

If you suspect the problem lies within a parser, it is likely that the dataformat has changed and broken the parsing code. (The text BLAST and GenBankformats seem to be particularly fragile.) Thus, the parsing code inBiopython is sometimes updated faster than we can build Biopython releases.You can get the most recent parser by pulling the relevant files (e.g. theones inBio.SeqIO orBio.Blast) from our git repository. However, becareful when doing this, because the code in github is not as well-testedas released code, and may contain new dependencies.

In any bug report, please let us know:

1. Which operating system and hardware (32 bit or 64 bit) you are using
2. Python version
3. Biopython version (or git commit/date)
4. Traceback that occurs (the full error message)

And also ideally:

5. Example code that breaks
6. A data file that causes the problem

Biopython is run by volunteers from all over the world, with many types ofbackgrounds. We are always looking for people interested in helping with codedevelopment, web-site management, documentation writing, technicaladministration, and whatever else comes up.

If you wish to contribute, please first readCONTRIBUTING.rst here,visit our web sitehttps://biopython.org and join our mailing list:https://biopython.org/wiki/Mailing_lists

• README.rst -- This file.
• NEWS.rst -- Release notes and news.
• LICENSE.rst -- What you can do with the code.
• CONTRIB.rst -- An (incomplete) list of people who helped Biopython inone way or another.
• CONTRIBUTING.rst -- An overview about how to contribute to Biopython.
• DEPRECATED.rst -- Contains information about modules in Biopython thatwere removed or no longer recommended for use, and how to update code thatuses those modules.
• MANIFEST.in -- Configures which files to include in releases.
• setup.py -- Installation file.
• Bio/ -- The main code base code.
• BioSQL/ -- Code for using Biopython with BioSQL databases.
• Doc/ -- Documentation.
• Scripts/ -- Miscellaneous, possibly useful, standalone scripts.
• Tests/ -- Regression testing code including sample data files.