Install & Compatibility
Where this runs
tested against v0.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.751s · 24MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 4.5s · import 0.685s · 25MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_client
✓ from biothings_client import get_client
✗ import mygene
mg = mygene.MyGeneInfo()
The `biothings_client` is the unified client. Older, specific clients like `mygene` or `myvariant` are now wrappers and may be deprecated.
This quickstart demonstrates how to instantiate clients for MyGene.info and MyVariant.info, fetch a single gene by ID, query multiple genes by symbol, and fetch a variant annotation. It uses common fields for demonstration.
from biothings_client import get_client
# Get a client for the MyGene.info API
mg_client = get_client("gene")
# Fetch gene annotation for a specific Entrez gene ID
gene_id = "1017" # Example: CDK2 gene
result = mg_client.getgene(gene_id, fields="symbol,name,entrezgene")
print(f"Gene ID {gene_id}: {result.get('symbol')} - {result.get('name')}")
# Query multiple genes by symbol
gene_symbols = ["CDK2", "BRCA1", "TP53"]
results = mg_client.querymany(gene_symbols, scopes="symbol", fields="name,entrezgene,ensembl.gene")
for res in results:
print(f"Symbol: {res.get('query')}, Name: {res.get('name')}, Entrez: {res.get('entrezgene')}")
# Get a client for the MyVariant.info API
mv_client = get_client("variant")
# Fetch variant annotation
variant_id = "chr1:g.140453134T>C"
variant_result = mv_client.getvariant(variant_id)
# print(f"Variant {variant_id}: {variant_result}") # Uncomment to see full result
print(f"Variant {variant_id}: {variant_result.get('_id')} - {variant_result.get('dbsnp', {}).get('rsid')}")
Debug
Known issues
breakingSupport for Python 3.6 was dropped in version 0.5.0. The last version to support Python 3.6 is 0.4.1. Python <=3.5 (including 2.7) was dropped as of version 0.4.0, with 0.3.1 being the last supporting version.fixUpgrade to Python 3.7 or newer. For caching features, Python 3.8 or newer is required.
affects: >=0.5.0 for Python 3.6, >=0.4.0 for Python <=3.5
breakingVersion 0.4.0 replaced the underlying HTTP client from `requests` to `httpx` and the caching library from `requests_cache` to `hishel`. Code directly interacting with these internal components or expecting their behavior might break.fixReview any code that relied on `requests` or `requests_cache` internals or direct imports. Update to use the `biothings_client`'s public API or `httpx` and `hishel` directly if custom HTTP/caching logic is needed.
affects: >=0.4.0
breakingVersion 0.4.0 introduced an `ImportError: cannot import name 'alwayslist' from 'biothings_client'` for some downstream libraries. This indicates a change in the public API or internal structure.fixEnsure `biothings_client` is updated to a version that includes fixes for this import error (e.g., 0.4.1 or later) or adjust imports in dependent code.
affects: 0.4.0
gotchaThe caching feature (`biothings_client[caching]`) explicitly requires Python >=3.8. It will not be available or function correctly on Python 3.7.fixIf caching is desired, ensure your Python environment is 3.8 or newer.
affects: <0.5.0 (for Python 3.7 users trying to use caching)
gotchaOlder, specific BioThings API clients (e.g., `mygene.py`, `myvariant.py`) are now thin wrappers around `biothings_client` and are expected to be deprecated in the future.fixNew projects and existing projects should migrate to using `biothings_client` directly via `from biothings_client import get_client` to ensure future compatibility.
affects: All versions
gotchaWhen requesting data as pandas DataFrames (using `as_dataframe=True`), especially for APIs returning very large or complex objects (e.g., `MyChem.info`), deeply nested data structures might lead to hard-to-use DataFrames or even cause hangs.fixAvoid requesting entire objects as DataFrames without specifying particular fields, or manually parse the JSON response if the structure is too complex for direct DataFrame conversion.
affects: All versions when using `as_dataframe=True`
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'biothings_client'
The 'biothings_client' package is not installed in the current Python environment.
fixpip install biothings_client
ImportError: cannot import name 'alwayslist' from 'biothings_client'
This error typically occurs when using an outdated `biothings-client` version (e.g., 0.4.0) where `alwayslist` was removed or moved, and older code from `mygene.py` or similar clients is being used. The current version (0.5.0) uses a different import structure.
fixUpgrade to the latest `biothings-client` version using `pip install --upgrade biothings_client` and adjust imports to use `from biothings_client import get_client` for client instantiation.
requests.exceptions.HTTPError: 400 Client Error: Expect type list
The `querymany` method expects a list of IDs or queries as its primary argument, but a non-list type (e.g., a single string) was provided.
fixEnsure the argument passed to `querymany` is always a list, even for a single item. For example, `client.querymany(['gene_id_1'])` instead of `client.querymany('gene_id_1')`. ModuleNotFoundError: No module named 'pandas'
This occurs when trying to use the dataframe output features of `biothings-client` without installing the optional `dataframe` dependencies.
fixInstall `biothings-client` with the `dataframe` extra: `pip install biothings_client[dataframe]`
Upgrade
Version history
0.5.1latest on PyPI · released Jul 23, 2026
Audit
Dependencies
pandasoptionalRequired for returning query results as DataFrame objects, installed via `biothings_client[dataframe]` extra.
hisheloptionalRequired for local SQLite caching, installed via `biothings_client[caching]` extra.
anysqliteoptionalRequired for local SQLite caching, installed via `biothings_client[caching]` extra.