PySRAdb

2.5.1 verified Fri May 01 auth: no python

pysradb is a Python tool for querying and downloading metadata and data from NCBI SRA (Sequence Read Archive), ENA (European Nucleotide Archive), and GEO (Gene Expression Omnibus). It provides CLI and Python interfaces to search experiments, samples, runs, and download FASTQ/SRA files. Current version 2.5.1 (released 2025, active development).

pip install pysradb

Common errors

error ModuleNotFoundError: No module named 'pysradb' ↓

cause pysradb not installed or installed in a different environment.

fix

Run: pip install pysradb

error AttributeError: module 'pysradb' has no attribute 'SRA' ↓

cause Trying to use old import pattern from pysradb <2.0.0.

fix

Use: from pysradb import SRA database

error HTTPError: 429 Client Error: Too Many Requests ↓

cause Excessive API calls to NCBI servers triggering rate limit.

fix

Add a delay between requests (e.g., time.sleep(1)) or reduce query frequency.

Warnings

breaking In v2.0.0, the API was completely rewritten. The old SRA class and CLI commands are replaced. Scripts using pysradb <2.0.0 will break. ↓

fix Migrate to new API: use 'from pysradb import SRA database' and new method signatures.

gotcha The '.search()' method may return empty results if the query is too specific or server timeout. Always check if the returned DataFrame is empty. ↓

fix Wrap search in a try-except or check df.empty after calling search.

deprecated The 'sradb' command-line entry point is deprecated in favor of 'pysradb' CLI. Using 'sradb' will emit a warning and may be removed in future. ↓

fix Use 'pysradb' instead of 'sradb' for CLI commands.

Imports

SRA database
wrong
```
import pysradb
```
correct
```
from pysradb import SRA database
```
The main class is SRA database, not the package directly.

Quickstart

Initialize the SRA database and search for studies related to a gene/term.

from pysradb import SRA database
db = SRA database()
df = db.search('SMAD4', n=5)
print(df[['study_accession', 'experiment_title', 'sample_accession']].head())