How to Retrieve Metagenomic Proteins from the AlphaFold Database

By Dr. Zubair Khalid, DVM, MS, PhD · 2026-11-11

Metagenomics, the sequencing of genetic material recovered directly from environmental samples, routinely surfaces thousands of proteins with no experimental structure and often no close characterized relative. The AlphaFold Database (AFDB) closes much of that gap. It holds computed 3D models for the bulk of known protein sequence space, including proteins drawn from large-scale metagenomic sequence studies, a change that has produced an exponential increase in publicly available structural models [1]. AlphaFold for metagenomics is therefore mostly a retrieval problem. The model you need usually already exists, and the real work lies in mapping your identifiers, downloading the right files, and judging whether each model is trustworthy.

By the end of this guide you will be able to:

1. Map RefSeq accessions, locus tags, or an NCBI taxonomy ID to AlphaFold DB entries.
2. Download single models with curl and batches with a short Python script.
3. Choose between PDB, mmCIF, binary mmCIF (bCIF), and PAE JSON files.
4. Read pLDDT and predicted aligned error (PAE) values before you trust a model.
5. Run structure similarity searches and functional annotation on what you retrieve.

Have this on hand before you start:

• A list of protein accessions from your project. These can be MGnify protein entries, RefSeq protein accessions from NCBI, locus tags from your own annotation of a metagenome-assembled genome (MAG), or UniProt accessions.
• Python 3.8 or newer with the requests package installed.
• curl or wget.
• Optional: Biopython for parsing coordinates, Foldseek for clustering, and a molecular viewer such as ChimeraX or PyMOL.

What the AlphaFold Database Contains for Metagenomics

The AFDB is operated by EMBL-EBI together with Google DeepMind. The first release in 2021 covered proteins from 21 species [2]. The database then expanded to essentially all of UniProt, more than 200 million structures, and beyond curated proteomes to proteins from large-scale metagenomic sequence studies [1]. Metagenomic proteins reach the database through UniProt imports and through metagenomic protein catalogs such as MGnify, EMBL-EBI's resource for metagenomic assemblies and proteins.

Three properties of AFDB entries shape everything you do downstream:

• Each entry is a single polypeptide chain. Models contain no ligands, cofactors, metal ions, post-translational modifications, or binding partners.
• Every entry ships with coordinates in PDB and mmCIF formats, a compressed binary mmCIF (bCIF), and a PAE JSON file that stores the predicted aligned error matrix [3].
• Confidence is embedded in the files. The per-residue pLDDT score sits in the B-factor column of the coordinates, and the PAE matrix describes expected alignment error in Angstroms between every pair of residues.

The metagenomic payoff is real. Pfam curators now use AlphaFold models to refine domain boundaries and to discover entirely new protein families, with expanded curation of metagenomic families [4]. Enzyme hunters screen the database for new catalysts, a route that produced an engineered plastic-degrading hydrolase described later in this article [5].

How Metagenomic Protein Identifiers Map to AFDB Entries

Every retrieval project starts from identifiers, and metagenomic projects accumulate several kinds:

• Locus tags, such as bin1_00012, assigned when you annotate your own assembly with tools like Prodigal or Prokka.
• RefSeq protein accessions, which look like WP_ followed by digits and a version suffix after a period, when proteins come from NCBI's RefSeq database.
• MGnify accessions, when proteins come from EMBL-EBI's metagenomic catalogs.
• UniProt accessions, the 6-character identifiers such as P69905 or the 10-character A0A-prefixed identifiers, which AFDB uses as its primary key for UniProt entries.

AFDB file names are built from these accessions, so the mapping step is where most metagenomic retrieval projects stumble. Locus tags are unstable across annotation runs, and old and new locus tag formats coexist in NCBI records, which is why mapping tools accept both [3].

The AlphaFoldDB Structure Extractor was built for exactly this step. It is an open-access web server and API that accepts NCBI taxonomy IDs, RefSeq accessions, locus tags in old and new formats, and UniProt or AlphaFold accessions. It returns structure files in PDB, mmCIF, bCIF, or PAE JSON format, generates an ID mapping file that traces each input identifier back to its standard accession, and reports unmapped IDs separately so you can retry them with a different identifier type. A mapping-only mode covers cases where you want the resolved accessions but not the coordinate files, and a documented API supports integration into bioinformatics pipelines. The developers tested the tool with individual inputs and with batches up to 5,000 accessions of each identifier type [3]. The server is hosted at https://project.iith.ac.in/sharmaglab/alphafoldextractor/.

Choose a Retrieval Route

Different questions need different entry points into the database.

Retrieving AlphaFold Metagenomics Proteins Step by Step

This walkthrough assumes a common scenario: you annotated a MAG from a soil metagenome, you have a table of proteins with locus tags and rough functional notes, and you want structures for the hypothetical proteins that interest you. The same steps work for RefSeq or MGnify accessions.

Step 1: Collect and normalize your accessions

Save one accession per line in a plain text file. Keep the version suffix on RefSeq accessions and keep the original locus tag in a second column of your annotation table, because you will need both for provenance later.

bin1_00012
bin1_00087
bin1_00103

If your accessions are already UniProt accessions, you can skip the mapping step entirely and go straight to downloads.

Step 2: Map accessions to AFDB IDs

Open the Structure Extractor web server [3], select the input type that matches your list, and paste up to a few thousand accessions. Choose the output formats you want, then run the job. You receive:

• Structure files in the formats you selected.
• An ID mapping file with one row per input identifier and its resolved standard accession.
• A separate list of unmapped IDs.

Download and archive the mapping file with your raw data. When an annotation rerun a year later produces different locus tags for the same scaffold, the mapping file is the only record of which structure belongs to which original gene call [3].

If you prefer code, the same tool documents an API so the mapping and download logic can run inside a pipeline without a browser [3].

Step 3: Download a single model with curl

AFDB coordinates live at predictable URLs built from the accession, the fragment number, and the model version:

https://alphafold.ebi.ac.uk/files/AF-{accession}-F{fragment}-model_v{version}.cif

For example, to fetch the model for the UniProt entry P69905:

curl -f -O "https://alphafold.ebi.ac.uk/files/AF-P69905-F1-model_v4.cif"

curl prints a progress meter and writes AF-P69905-F1-model_v4.cif into the current directory. The first lines of the file look like this:

data_AF_P69905-F1-model_v4
#
loop_
_atom_site.group_PDB
_atom_site.type_symbol
_atom_site.label_atom_id

Three parts of the URL deserve explanation:

• The accession is the UniProt-style identifier for the protein.
• F1 is the fragment number. Most entries are a single fragment, but proteins whose mature chains are split carry F2, F3, and so on as separate files.
• model_v4 is the database version. Versions increment when structures are re-predicted, so if a v4 URL ever returns an error, check the entry on the AFDB website for the current version before rewriting your script.

The -f flag tells curl to fail with a nonzero exit code on HTTP errors instead of silently saving an error page as your structure file. That single flag prevents the most annoying batch-download bug, a directory full of 404 pages that look like data.

Step 4: Pick the right file format

AFDB offers four file types, and the choice matters:

• PDB. The legacy text format with the widest tool support. Atom serial numbers top out at 99,999 and chain identifiers are a single character, so very large metagenomic proteins, some of which run to thousands of residues, can exceed the format's limits.
• mmCIF. A key-value text format with no practical size limit. This is the format AFDB itself distributes and the safest default for scripts.
• bCIF. Binary-compressed mmCIF. Files are much smaller and load faster in modern viewers such as Mol*, at the cost of needing a parser that understands the compression.
• PAE JSON. No coordinates at all. It stores the predicted aligned error matrix, which you need for domain-level confidence analysis.

Step 5: Batch download with Python

For tens to thousands of mapped accessions, a small script with polite pacing beats a tight loop:

import time
import requests

accessions = ["P69905", "P02769"]  # replace with your mapped AFDB accessions

for acc in accessions:
    url = f"https://alphafold.ebi.ac.uk/files/AF-{acc}-F1-model_v4.cif"
    try:
        r = requests.get(url, timeout=60)
        if r.status_code == 200:
            out = f"AF-{acc}-F1-model_v4.cif"
            with open(out, "wb") as fh:
                fh.write(r.content)
            print(f"saved {out}")
        else:
            print(f"{acc}: HTTP {r.status_code}")
    except requests.RequestException as err:
        print(f"{acc}: {err}")
    time.sleep(1)

Representative output:

saved AF-P69905-F1-model_v4.cif
saved AF-P02769-F1-model_v4.cif

Parameter notes:

• timeout=60 stops the script from hanging forever on a stalled connection.
• time.sleep(1) spaces requests out. Public database servers throttle aggressive clients, and a one second pause rarely costs anything at these scales.
• The status code check separates a genuine 404, which means the accession has no model or the version is wrong, from a network failure, which deserves a retry.

When downloads fail, the messages tell you which fix to apply:

• curl: (22) The requested URL returned error: 404 means the accession has no model or the version suffix is stale. Verify the accession and check the entry page on the AFDB website for the current version.
• HTTP 403 or HTTP 429 responses mean the server is throttling you. Increase the delay between requests and move very large jobs to the bulk archive described below.
• requests.exceptions.ConnectTimeout is a network problem on your side. Retry with a longer timeout before assuming anything is wrong with the accession.

Step 6: Check model confidence before you use anything

The AlphaFold documentation defines four pLDDT bands, and they should gate how you use each model:

• Above 90: backbone and side chain geometry are usually accurate.
• 70 to 90: the backbone is usually accurate, side chain positions vary.
• 50 to 70: low confidence, treat the local shape as a rough guide.
• Below 50: frequently intrinsically disordered, and the geometry should not be interpreted.

pLDDT is stored in the B-factor column of the coordinate files, so a short function reads it out of a PDB format file:

def read_plddt(path):
    values = []
    with open(path) as fh:
        for line in fh:
            if line.startswith("ATOM"):
                values.append(float(line[60:66]))
    return values

vals = read_plddt("AF-P69905-F1-model_v4.pdb")
print(len(vals), min(vals), round(sum(vals) / len(vals), 1))

The printout gives three numbers: residue count, lowest pLDDT, and mean pLDDT. A compact globular domain typically averages in the 90s, while unmodeled tails and long linkers drag the minimum below 50. Low confidence at the termini of metagenomic proteins is common and usually flags real disorder rather than a broken file. Work on AlphaFold model classification has noted the correlation between model confidence and intrinsic disorder, which is exactly why a low-scoring tail should make you suspect the protein is flexible, not that the download failed [2].

Run two sanity checks on every file. First, the residue count should match the length of the underlying protein sequence in your FASTA, which catches truncated downloads. Second, open the model in a viewer and confirm the chain is continuous, since a file that ends mid-atom-record is a corrupted download.

For multi-domain proteins, mean pLDDT is not enough. Download the PAE JSON file as well. It contains the predicted aligned error matrix plus a maximum predicted aligned error value, and the AFDB entry page renders the same matrix as a heatmap. Low PAE between two regions means their relative orientation is confident. High PAE between domains means the domains are individually reliable but their arrangement is a guess, which matters enormously if you plan docking or interface analysis.

Step 7: Annotate and compare what you retrieved

Structures without interpretation are just files. The standard next moves:

• Attach domain annotation with InterPro and Pfam. Pfam's current release integrates with InterPro and has expanded metagenomic family curation, with AlphaFold models used to refine domain boundaries and identify new domains [4].
• Search for structural relatives. AlphaFind accepts a UniProt ID, a PDB ID, or a gene symbol and returns the most structurally similar chains across AFDB with similarity metrics and 3D superposition views, free and without registration at https://alphafind.fi.muni.cz [6]. 3D-AF-Surfer offers real-time fold-level classification of AlphaFold models using 3D Zernike descriptors, a rotationally invariant mathematical representation of 3D shapes, fed to a neural network that retrieves same-fold proteins more accurately than direct descriptor comparison [2].
• Cluster large collections. Foldseek aligns structures at scale, and FoldMason supports multiple structure alignment, which is how recent effector-protein workflows cluster predicted models into families [7].
• Infer function from shape. The WASP pipeline uses structural homology and network topology to transfer annotations, and on 20 industrially relevant organisms it recovered annotations for 20 to 30 percent of previously uncharacterized proteins [9].
• Compute residue-level properties. ProCaliper pulls annotation and structure data from UniProt and AlphaFold DB and computes charge, solvent accessibility, and protonation states per residue [10].
• Prepare structures for simulation. PypKa provides pKa predictions and pH-dependent protonation states compatible with the AMBER, CHARMM, and GROMOS force fields, with results precomputed for over 200,000 structures from the PDB and AlphaFold DB and available through an API at pypka.org [11].
• Compare against experiment. RCSB.org lets you search, group, and visualize experimental PDB structures alongside computed structure models, which is the fastest way to sanity-check an AFDB model against a crystal or cryo-EM structure of a homolog [1].

Bulk Retrieval at Pipeline Scale

Three practical tips keep large jobs moving:

1. Use the Structure Extractor API for anything you will rerun. The API exists so that mapping and retrieval can sit inside a pipeline, and the tool has been exercised with batches in the thousands of accessions per identifier type [3].
2. Use the mapping-only mode when you only need accessions. Coordinate files add up fast, and a mapping pass first lets you filter to the proteins you actually want [3].
3. Switch to the EMBL-EBI bulk archive for database-scale needs. The full AlphaFold DB is available for bulk download at https://ftp.ebi.ac.uk/pub/databases/alphafold/, which avoids per-file requests entirely when you need thousands of structures or more.

A simple paced shell loop covers medium-sized jobs:

while read acc
do
  curl -f -s -O "https://alphafold.ebi.ac.uk/files/AF-${acc}-F1-model_v4.cif"
  sleep 1
done < mapped_accessions.txt

The -s flag silences the progress meter so log files stay readable, and -f keeps failed requests from writing junk files. Log anything that fails and rerun the failures once at the end.

Finding Structural Relatives of a Metagenomic Protein

Sequence similarity fails exactly where metagenomics hurts most, because many environmental proteins have no close sequence homologs with characterized structure. Structure-based search fills that hole.

• AlphaFind indexes the entire set of AFDB structures by 3D features extracted automatically from each chain, then uses a machine learning model to return the most similar structures for a query, complete with similarity metrics and superposition visualizations [6].
• 3D-AF-Surfer represents each structure with 3D Zernike descriptors and classifies AlphaFold2 models by fold in real time, which also supports large-scale fold surveys of a retrieved protein set [2].
• MrParse takes a protein sequence, optionally crystallographic reflection data, and consolidates homology predictions in one place. It ranks experimental homologues from the PDB using eLLG, a score that indicates how likely a given search model is to work in molecular replacement, and it also identifies and ranks homologues in the EBI AlphaFold database. Built-in displays of predicted secondary structure, coiled-coil regions, and transmembrane segments inform the choice of protocol [8]. Crystallographers are the primary audience, but the homologue ranking is equally useful for triaging a metagenomic protein before you commit lab resources.

What Researchers Do With Retrieved Metagenomic Structures

The retrieval workflow above is the front end of projects like these:

• Plastic-degrading enzymes. A structure-guided bioinformatic workflow screening the AlphaFold protein structure database identified a novel poly(ethylene terephthalate) hydrolase, LSPET4, from Micromonospora sp. HM5-17. The enzyme carries a carbohydrate-binding module that binds PET surfaces, and rational engineering produced a variant with 38.79-fold higher activity than the wild type, comparable to the best reported PET hydrolase derived from IsPETase at 45 degrees Celsius [5].
• Nucleoid-associated proteins. Nucleoid-associated proteins organize bacterial genomes by bending, wrapping, and bridging DNA. With metagenome collections growing constantly, researchers recommend simple in vitro biochemical assays to characterize new candidates and highlight AlphaFold models as a practical characterization tool for nucleoid-associated proteins from metagenomes [12].
• Fungal effectors. A published workflow for Ustilago maydis effector proteins retrieves models from the AlphaFold Protein Structure Database or generates them de novo with AlphaFold 3 or ColabFold, then clusters structures with FoldMason and Foldseek to infer functional relationships [7].
• Proteome-scale crosslink mapping. AlphaCross-XL automatically retrieves protein structures from the AlphaFold Protein Structure Database and maps cross-linked peptides onto them at proteome-wide scale, extending crosslinking mass spectrometry beyond single purified proteins [13].

When No Model Exists: AlphaFold Server and Local Prediction

Retrieval fails in three situations: the protein has no AFDB entry, you need a complex with a ligand or nucleic acid, or you need a specific construct rather than the full-length sequence. Then you predict instead of download.

The AlphaFold Server is the official web application for AlphaFold 3, available at https://alphafoldserver.com for non-commercial use. It predicts assemblies of proteins with other proteins, nucleic acids, ions, and small molecules, none of which AFDB single-chain models can give you. For batch or custom runs, ColabFold provides AlphaFold 2 predictions in a notebook environment and is the standard choice in published metagenomic workflows [7].

An AlphaFold tutorial that covers running predictions yourself is a good investment at this point, but check AFDB first. Downloading an existing model takes seconds, while a prediction run takes minutes to hours per protein and hands you one more model that still needs the same confidence checks.

Common Mistakes and Limitations

These are the errors that cost people the most time:

1. Treating a model as an experimental structure. AFDB entries are predictions. Where an experimental structure exists for the protein or a close homolog, compare them directly, which RCSB.org supports for computed models and PDB entries side by side [1].
2. Reading pLDDT as an error in Angstroms. pLDDT is a per-residue confidence score from 0 to 100. The residue-pair error estimate is the PAE matrix, and it is the number you need for judging domain packing.
3. Judging a whole protein by its mean pLDDT. Multi-domain metagenomic proteins often carry confident domains joined by low-confidence linkers. Use PAE to decide whether inter-domain orientations are trustworthy, and remember that low-scoring tails frequently mark genuine intrinsic disorder [2].
4. Using PDB files for very large proteins. Atom serial numbers in PDB format stop at 99,999 and chain identifiers are one character. Long metagenomic proteins need mmCIF.
5. Expecting ligands, cofactors, or complexes. AFDB models are single chains with no bound molecules and no quaternary assembly. For those, use the AlphaFold Server or local AlphaFold 3.
6. Hard-coding model_v4 everywhere. Version suffixes change when the database re-predicts models. A stale version returns a 404, which people then misread as a missing protein.
7. Discarding the ID mapping file. Without it you cannot trace a structure back to the original locus tag, and old versus new locus tag formats make the problem worse over time [3].
8. Ignoring the unmapped list. Unmapped IDs usually mean a coverage gap or an identifier-type mismatch. Retry them with a different accession type before concluding the protein has no model [3].
9. Hammering the server with a tight loop. Aggressive clients get throttled. Pace requests, use the API, and move database-scale jobs to the bulk archive [3].
10. Treating a structural match as a function. Structural similarity generates hypotheses. Even pipelines built for structural annotation, such as WASP, produce candidates that need experimental confirmation [9].

The honest limitation underneath all of this: AFDB gives you a static, single-chain, uncertainty-tagged guess at a structure. It is the best starting point most metagenomic proteins have ever had, and it is still a starting point.

Frequently Asked Questions

Are metagenomic proteins included in the AlphaFold Database?

Yes. The database expanded beyond curated proteomes to include proteins from large-scale metagenomic sequence studies, and metagenomic proteins enter through UniProt imports and metagenomic catalogs such as MGnify [1]. Coverage is broad but not total, so treat identifier mapping as a real step rather than a formality.

How do I download AlphaFold structures for an entire metagenome?

Map your protein accessions to AFDB IDs first, using a tool such as the AlphaFoldDB Structure Extractor, then batch-download the mapped accessions with a paced script or the tool's API [3]. Keep the mapping file, and move to the EMBL-EBI bulk archive for very large jobs.

Should I use PDB or mmCIF files from the AlphaFold Database?

Use mmCIF as your default. PDB format caps atom serial numbers at 99,999 and restricts chain identifiers to one character, which breaks on very large proteins. bCIF is the compressed variant to use when file size or viewer loading speed matters.

What pLDDT cutoff should I trust?

Above 90, trust backbone and side chains. From 70 to 90, trust the backbone. From 50 to 70, treat the shape as a rough guide. Below 50, expect disorder and do not interpret the geometry. These bands come from the AlphaFold documentation.

What is the difference between the AlphaFold Database and the PDB?

The PDB archives experimentally determined structures, while AFDB stores computed predictions. RCSB.org now lets you search, group, and visualize both kinds side by side [1].

Can I search the AlphaFold Database by structure similarity?

Yes. AlphaFind accepts a UniProt ID, PDB ID, or gene symbol and returns similar AFDB chains with similarity metrics and superpositions [6]. 3D-AF-Surfer provides fold-level classification of AlphaFold models [2].

Why is my protein accession unmapped?

Usually the identifier type does not match what the mapping tool expects, or the protein has no model. Mapping tools report unmapped IDs separately, and retrying with a different accession format, for example a RefSeq accession instead of an old locus tag, resolves many cases [3].

When should I predict a structure instead of downloading one?

When the protein has no AFDB entry, when you need a complex with ligands or nucleic acids, or when you need a custom construct. Use the AlphaFold Server for AlphaFold 3 complex predictions or run ColabFold locally [7].

Sources

1. RCSB Protein Data Bank: visualizing groups of experimentally determined PDB structures alongside computed structure models of proteins.
2. Real-time structure search and structure classification for AlphaFold protein models.
3. AlphaFold Database Structure Extractor: a web server and API to download AlphaFold structures using common protein accessions.
4. The Pfam protein families database: embracing AI/ML.
5. Structure-guided discovery and rational design of a new poly(ethylene terephthalate) hydrolase from AlphaFold protein structure database.
6. AlphaFind: discover structure similarity across the proteome in AlphaFold DB.
7. Computational Identification and Structural Analysis of Ustilago maydis Effector Proteins.
8. MrParse: finding homologues in the PDB and the EBI AlphaFold database for molecular replacement and more.
9. WASP: a pipeline for functional annotation prediction based on AlphaFold structural models.
10. ProCaliper: functional and structural analysis, visualization, and annotation of proteins.
11. PypKa server: online pKa predictions and biomolecular structure preparation with precomputed data from PDB and AlphaFold DB.
12. Identification, characterization and classification of prokaryotic nucleoid-associated proteins.
13. AlphaCross-XL: A Seamless Tool for Automated and Proteome-Scale Mapping of Cross-Linked Peptides Onto 3D Protein Structures.