MGni.py

MGni.py (🔉IPA:'mæɡni-paɪ') is a lightweight python client and toolkit for the MGnify API v2.

Contents

• Features
• Available API Endpoints
• Installation
• Quick Start
• Additional Documentation
• Development
• License
• Citation

Features

• FAIR: More findable MGnify analyses and metadata, returned in familiar metagenomics data formats (e.g., GFF, Darwin Core, Dataframes [pandas, polars, anndata])
• Simplifies API interactions: Let MGni.Py handle the complexity of building, executing, and parsing API calls so you can focus on the data!
• Fast: MGni.Py uses caching to speed up API expolation, as well as supports both sync and async API calls

Supported MGnify API resources

• Studies
• Samples
• Publications
• Genomes
• Catalogues
• Runs
• Assemblies
• Analyses
• Biomes (GOLD ecosystem classifications)

Installation

From PyPI

pip install mgnipy

Development installation

git clone https://github.com/EBI-Metagenomics/mgnipy.git
cd mgnipy
uv sync --all-groups  # or: pip install -e ".[dev,docs]"

Quick Start

🚀 1. Initialize mgnipy.MGnipy

from mgnipy import MGnipy

# Create the main client, with default configuration
mg = MGnipy()

# See available endpoints
mg.list_resources()

🔎 2. Search resources with a mgnipy.MGnifier

Building the query set

# Search for studies keyword
studies = mg.studies(
    search="disease"
)

# Can preview requests before fetching
studies.explain()

Executing the queries

# client context manager
with MG: 

    # get page by page via .get()
    studies.get()
    # or via .page(), getting a specific pg num 
    studies.page(2)
    # OR potentially all at once in large batches (also async option .aget_all())
    studies.get_all()

    # then can enrich list with detailed metadata
    studies.enrich_details()

Viewing the search results

# the mgnify list (without details)
study_list = studies.search_results
# detailed metadata, e.g. with enriched details
detailed_study_list = studies.metadata

# e.g. as dataframes
pl_metadata = detailed_study_metadata.to_polars()
pd_metadata = detailed_study_metadata.to_pandas()

# e.g. as json
json_metadata = detailed_study_metadata.to_json()

🗃️ 3. Explore a mgnipy.MGazine of datasets

# accessing the mgazine of datasets
mgazine = studies.datasets

# preview
print(mgazine)

Downloading datasets from MGnify

# download file by file 
mgazine.download(
    alias="mgnify_file_alias.fasta.gz", 
    to_dir="downloads_folder"
)

# or download all 
mgazine.download_all(to_dir="downloads_folder")

Reading in datasets from MGnify

# support for tsv, csv, txt, jsonl
taxa_table = mgazine.stream(
    alias="mgnify_file_alias.tsv", 
    df_engine="polars"
)

# support for fasta, gff, biom via skbio
skbio_fasta = mgazine.stream(alias="mgnify_file_alias.fasta.gz")

Additional Documentation

• Interactive OpenAPI documentation
• MGnify. 2026. “RESTful API.” July 13.
• MGnify. 2026. “Website and Portal.” July 13.
• mgnipy package docs
• openapi-python-client

Development

see Contributing.md

License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See the included LICENSE file for full terms.

Citation

If you use MGni.py in your work, please cite the project:

MGnipy contributors (2026). MGni.py: a lightweight Python client and toolkit for the MGnify API. Version 0.2.1. https://github.com/EBI-Metagenomics/mgnipy

BibTeX:

@software{mgnipy2026,
  author = {MGnipy contributors},
  title = {MGni.py: a lightweight Python client and toolkit for the MGnify API},
  year = {2026},
  version = {0.2.1},
  url = {https://github.com/EBI-Metagenomics/mgnipy}
}