BioServices Current version: 1.16.0 (Mar 27, 2026)

BioServices provides programmatic access to biological web services from Python.

BIOSERVICES: access to biological web services programmatically

Python_version_available:

BioServices is tested for Python 3.9, 3.10, 3.11, 3.12

Contributions:

Please join https://github.com/cokelaer/bioservices

Issues:

Please use https://github.com/cokelaer/bioservices/issues

How to cite:

Cokelaer et al. BioServices: a common Python package to access biological Web Services programmatically Bioinformatics (2013) 29 (24): 3241-3242

Documentation:

RTD documentation.

Bioservices is a Python package that provides access to many Bioinformatics Web Services (e.g., UniProt) and a framework to easily implement Web Services wrappers (based on WSDL/SOAP or REST protocols).

The primary goal of BioServices is to use Python as a glue language to provide a programmatic access to several Bioinformatics Web Services. By doing so, elaboration of new applications that combine several of the wrapped Web Services is fostered.

One of the main philosophies of BioServices is to make use of the existing biological databases (not to re-invent new databases) and to alleviate the need for expertise in Web Services for developers and users.

BioServices provides access to about 40 Web Services.

Installation

Install the latest stable release from PyPI:

pip install bioservices

or from conda-forge:

conda install conda-forge::bioservices

Contributors

Maintaining BioServices would not have been possible without users and contributors. Each contribution has been an encouragement to pursue this project. Thanks to all:

Quick example

Here is a small example using the UniProt Web Service to search for the zap70 specy in human organism:

>>> from bioservices import UniProt
>>> u = UniProt(verbose=False)
>>> data = u.search("zap70+and+taxonomy_id:9606", frmt="tsv", limit=3,
...                 columns="id,length,accession, gene_names")
>>> print(data)
Entry name   Length  Entry   Gene names
ZAP70_HUMAN  619     P43403  ZAP70 SRK
B4E0E2_HUMAN 185     B4E0E2
RHOH_HUMAN   191     Q15669  RHOH ARHH TTF

Note

major changes of UniProt API changed all columns names in June 2022. The code above is valid for bioservices versions >1.10. Earlier version used:

>>> data = u.search("zap70+and+taxonomy:9606", frmt="tab", limit=3,
...                 columns="entry name,length,id, genes")

Note that columns names have changed, the frmt was changed from tab to tsv and taxonomy is now taxonomy_id. Names correspondences can be found in:

u._legacy_names

More examples and tutorials are available in the On-line documentation

Command-Line Interface

BioServices also ships a bioservices command-line tool for quick lookups without writing any Python code:

$ bioservices --help

Four top-level commands are available:

• gene — query gene data (info, name, ontology, expression, pathway, ortholog, id mapping)

• protein — query protein data (search, sequence, structure, annotation, interaction, id mapping)

• taxonomy — retrieve taxonomic information for a taxon ID

• download-accession — download FASTA (and optionally GFF3/GenBank) for a sequence accession

Examples:

$ bioservices gene info --gene-id 1017
$ bioservices gene name --symbol BRAF
$ bioservices protein search --query ZAP70 --organism human
$ bioservices protein structure --uniprot-id P43403
$ bioservices taxonomy --id 9606
$ bioservices download-accession --accession FN433596.1

Full CLI reference: CLI documentation

Notebooks

The following Jupyter notebooks provide worked examples for many of the services. They can be viewed directly on nbviewer or downloaded and run locally.

Notebook	Description
Overview	Introduction and overview of BioServices
UniProt	Searching and retrieving data from UniProt
BioModels	Accessing BioModels database
ChEMBL	Drug and compound data from ChEMBL
Entrez/EUtils	NCBI Entrez utilities cookbook (ESearch, EFetch, EPost, ELink)
EUtils	EUtils quick example (ESummary and ESearch)
KEGG	KEGG pathways and databases
MUSCLE	Multiple sequence alignment with MUSCLE
NCBIBlast	Running BLAST searches via NCBI
WikiPathway	WikiPathways data access
Gene Mapping	Mapping gene identifiers across databases
BioMart	Querying BioMart data warehouses
Ensembl	Ensembl genome browser REST API
InterPro	Protein families and domains from InterPro
ENA	European Nucleotide Archive
Drug Discovery Pipeline	Integrated multi-service drug discovery workflow

Current services

Here is the list of services available and their testing status.

Service	CI testing
arrayexpress
bigg
biocontainers
biodbnet
biomart
biomodels
chebi
chembl
cog
dbfetch
ena
ensembl
eutils
eva
hgnc
intact_complex
kegg
muscle
mygeneinfo
ncbiblast
ncbiblastapi
omicsdi
omnipath
panther
pathwaycommons
pdb
pdbe
pfam
pride
pubchem
quickgo
reactome
rhea
seqret
unichem
uniprot
wikipathway

Note

Contributions to implement new wrappers are more than welcome. See BioServices github page to join the development, and the Developer guide on how to implement new wrappers.

Bioservices command

In version 1.8.2, we included a bioservices command. For now it has only one subcommand to download a NCBI accession number and possibly it genbank or GFF file (if available):

bioservices download-accession --accession K01711.1 --with-gbk

Changelog

Version	Description
1.16.0	New ncbiblastapi module: wraps NCBI’s own BLAST URL API, submitting jobs directly to NCBI (blastn, blastp, blastx, tblastn, tblastx) with support for NCBI databases (nt, nr, refseq_genomic, …) and optional API key for higher rate limits
1.15.0	Drop WSDL support: WSDLService class and suds-community dependency removed — all active services now use REST exclusively New HTTPResponseError type: HTTP errors are now returned as a rich object that behaves like int for backwards compatibility but raises a descriptive BioServicesError when mistakenly used as a dict or sequence (replaces silent TypeError crashes) New BioServicesError exception exported from bioservices.services and usable directly: from bioservices import BioServicesError Remove obsolete _compat module (Python 2 shims); replace pkg_resources with importlib.metadata Code quality: replaced assert statements in production code with ValueError/TypeError; fixed bare except: clauses, unused imports, and undefined name bugs across 15+ modules Test quality: replaced try/assert False/except/assert True anti-patterns with pytest.raises; intermittent tests marked flaky or xfail; slow tests given per-test timeout overrides Bug fixes: reactome.py SVG save path, pathwaycommons.py isinstance typo, settings.py loop variable, ensembl.py NotImplementedError typo, wikipathway.py API response handling Documentation overhauled: new Quick Start, merged changelog, contributors folded into Help & Credits, ChangeLog page removed
1.14.0	New proteins module (EBI Proteins API) New string module (STRING protein interaction database) New geo module (NCBI Gene Expression Omnibus) PubChem: update to current PUG REST API Remove deprecated BioGRID and PSICQUIC services
1.13.0	ChEBI: new REST API (replacing SOAP)
1.12.2	Add taxonomy CLI subcommand (via EUtils)
1.11.0	Remove ReactomeOld, ReactomeAnalysis, rnaseq_ebi (deprecated)
1.10.3	PDB: update to v2 API; remove biocarta (website no longer accessible)
1.10.1	PRIDE: update to new API (July 2022)
1.10.0	UniProt: update to new API (June 2022)
1.9.0	UniChem: update to new API
1.8.3	New biocontainers module
1.8.0	Remove chemspider, clinvitae, picr (deprecated) Add standalone bioservices CLI application
1.7.12	New cog module Deprecate PICR and TCGA modules PDB, ChEMBL, QuickGO, BioDBNet: new API
1.7.5	New mygeneinfo, pdbe modules
1.7.4	New bigg module (BiGG models) BioModels: new REST API (replacing WSDL) Move miriam to attic (deprecated)
1.7.0	New panther module
1.6.0	ChEMBL: fully rewritten to new API
1.5.2	Reactome: new API
1.5.0	BioDBNet, WikiPathways: migrate from WSDL to REST QuickGO, DBFetch: new API Rename readseq to seqret (new API)
1.4.8	New omnipath module
1.4.6	New rnaseq_ebi module
1.4.4	New ena module
1.4.1	HGNC: replaced deprecated module with genenames.org service
1.4.0	EUtils: migrate from WSDL to REST Remove apps/taxonomy (moved to biokit)
1.3.5	New intact module (Intact Complex)
1.3.4	New pride module
1.3.3	New ensembl, clinvitae modules
1.3.1	New readseq module
1.3.0	New REST class using requests (replacing urllib2) New eutils module Rename chembldb to chembl; rename WikiPathway to WikiPathways
1.2.3	New biodbnet, pathwaycommons modules
1.2.0	New muscle, geneprof modules
1.1.2	New biocarta, pfam modules
1.1.1	New hgnc module
1.1.0	New chebi, unichem modules
1.0.4	New pdb module (draft)
1.0.0	First stable release
0.9.0	Initial services: BioModels, KEGG, Reactome, ChEMBL, PICR, QuickGO, Rhea, UniProt, WSDbfetch, NCBIblast, PSICQUIC, WikiPathways

Warning

Some of the services may be down. BioServices developers are not responsible for the maintenance or failure of underlying services. Generally speaking (and by experience) the services are up most of the time but failure may occur because the site is under maintenance or too many requests have been sent. Another common reason is the fact that the API of the web services has changed: If so, BioServices need to be updated. You may contribute or report such API changes on our Issue page

Installation

BioServices is available on PyPi, the Python package repository. The following command should install BioServices and its dependencies automatically provided you have pip on your system:

pip install bioservices

If not, please see the external pip installation page or pip installation entry. You may also find information in the troubleshootings page section about known issues.

Regarding the dependencies, BioServices depends on the following packages: BeautifulSoup4 (for parsing XML), requests (for REST services) and easydev. All those packages should be installed automatically when using pip installer. BioServices also makes use of pandas and matplotlib to offer some extra functionalities.

User guide

• 1. Quick Start
  • 1.1. Introduction
  • 1.2. UniProt
  • 1.3. KEGG
  • 1.4. QuickGO
  • 1.5. BioModels
  • 1.6. Rhea
  • 1.7. Other services
• 2. Tutorials
  • 2.1. KEGG Tutorial
  • 2.2. Biomodels tutorial
  • 2.3. Protein test case study
  • 2.4. Manipulating compound identifiers
  • 2.5. Mapping identifiers
  • 2.6. BioMart service
• 3. Command-Line Interface
  • 3.1. gene
  • 3.2. protein
  • 3.3. taxonomy
  • 3.4. download-accession
• 4. Combining BioServices with external tools
  • 4.1. PYMOL
  • 4.2. BioPython
  • 4.3. Galaxy
• 5. Developer Guide
  • 5.1. Service module (REST)
  • 5.2. Naming convention
  • 5.3. Creating a service class (REST case)
  • 5.4. How to include tests ?
  • 5.5. Continuous integration
• 6. Gallery
• 7. NoteBooks
  • 7.1. ArrayExpress
  • 7.2. UniProt
  • 7.3. BioModels
  • 7.4. ChEMBL
  • 7.5. Entrez/Eutils
  • 7.6. KEGG
  • 7.7. MUSCLE
  • 7.8. NCBIBlast
  • 7.9. WikiPathway
• 8. Services
  • 8.1. ArrayExpress
  • 8.2. Biocontainers
  • 8.3. BiGG
  • 8.4. BioDBnet
  • 8.5. BioMart
  • 8.6. BioModels
  • 8.7. ChEBI
  • 8.8. ChEMBL
  • 8.9. COG
  • 8.10. ENA
  • 8.11. Ensembl
  • 8.12. EVA
  • 8.13. EUtils
  • 8.14. GEO (NCBI Gene Expression Omnibus)
  • 8.15. GeneProf
  • 8.16. QuickGO
  • 8.17. Kegg
  • 8.18. HGNC
  • 8.19. Intact (complex)
  • 8.20. InterPro
  • 8.21. MUSCLE
  • 8.22. MyGeneInfo
  • 8.23. NCBIblast
  • 8.24. NCBIBlastAPI
  • 8.25. OmniPath Commons
  • 8.26. Panther
  • 8.27. Pathway Commons
  • 8.28. PDB/PDBe modules
  • 8.29. PRIDE module
  • 8.30. Pfam
  • 8.31. PubChem
  • 8.32. Rhea
  • 8.33. Reactome
  • 8.34. Readseq
  • 8.35. STRING
  • 8.36. UniChem
  • 8.37. UniProt
  • 8.38. DBFetch
  • 8.39. Wikipathway
• 9. Applications and extra tools
  • 9.1. Peptides
  • 9.2. FASTA
• 10. References to BioServices on the Web
• 11. Scientific Literature
• 12. Help & Credits
  • 12.1. General Errors
  • 12.2. General questions
  • 12.3. Specific Usage
  • 12.4. Interest of the BioServices REST base class
  • 12.5. Credits