Who this is for
This guide is for researchers and students who want to call AlphaGenome 2 from Python for genomic prediction. By the end you should have the alphagenome package installed, an API key configured, and a working example that predicts and scores a variant's effect.
What AlphaGenome 2 is
AlphaGenome 2 is Google DeepMind's genomics model. It does not run on your machine. You call the hosted model through the lightweight alphagenome Python client, so no local GPU is needed[2]. The model takes a DNA sequence of up to 1 Mb together with a species and a condition, and predicts observed and imputed coverage tracks, gene expression, splicing and contact maps[3].
The condition is the central idea. Each call predicts for one condition: a reference tissue or cell type passed as condition=, where composite conditions such as UBERON:0000178_CL:0001054 are allowed, or your own single-cell data passed as cell_conditioning= with up to 256 cells[1]. To compare conditions, loop over them, or use batch arguments such as conditions=[1].
AlphaGenome Atlas is a separate route. It offers pre-computed effects for human variants without running the model, through a zero-code website or an Atlas API[1]. To reproduce results from the AlphaGenome paper, score variants across all tissues and cell types at once, or predict PRO-cap, use AlphaGenome 1 instead[1].
What you need
- A system: Linux, macOS or Windows. No local GPU is required[2].
- An account: apply for a free AlphaGenome API key. Both model predictions and Atlas queries need it[2].
- A Python environment: a virtual environment keeps the dependencies separate from the rest of your system.
Install the alphagenome package
The most direct route is pip. Create and activate a virtual environment, then install the latest PyPI release[2]:
python3 -m venv .venv
source .venv/bin/activate
pip install alphagenomeWith uv, run uv venv, then uv pip install alphagenome. In an existing uv project, uv add alphagenome adds the package directly. With conda, run conda create -n alphagenome python -y and conda activate alphagenome, then install with pip. If you want to work from source, clone the GitHub repository and run pip install -e . inside it. After upstream changes, run git pull and then pip install -e . again[2].
In Google Colab, the first cell of every notebook installs the package with ! pip install alphagenome. To keep the key out of your code, store it in the Secrets panel under the name ALPHA_GENOME_API_KEY and turn on Notebook access[2].
Configure the API key
When you run scripts or Jupyter notebooks locally, export the key as an environment variable. The line below can also go into ~/.zshrc or ~/.bashrc[2]:
export ALPHA_GENOME_API_KEY="YOUR_API_KEY"colab_utils.get_api_key() reads this variable first and falls back to Colab Secrets, so the same code runs locally and in Colab[2].
To check the installation and the key, run the script below. It prints the number of supported human conditions[2]:
from alphagenome import colab_utils
from alphagenome.models.v2 import dna_client
dna_model = dna_client.create(colab_utils.get_api_key())
print(len(dna_model.supported_conditions()), 'supported human conditions')A first example: a variant's effect on GLB1L expression
The official example uses CD14-positive monocytes in blood (UBERON:0000178_CL:0001054). The variant sits on chr2 at position 219243701, with reference base C and alternate base T, and the gene of interest is GLB1L[1]. The workflow has four steps: choose a condition, select a region, predict or score, and plot.
- Choose a condition with
condition = 'UBERON:0000178_CL:0001054'. - Select a region.
variant.reference_interval.resize(dna_client.SEQUENCE_LENGTH_1MB)builds a 1 Mb interval centred on the variant[1]. - Predict and score.
predict_variantwithrequested_outputs=[dna_client.OutputType.RNA_SEQ]returns RNA-seq tracks for the reference (REF) and alternate (ALT) sequences.score_variantapplies the recommended RNA-seq scorer across the interval, andtidy_scoresfilters the table to GLB1L[1]. - Plot.
plot_components.OverlaidTracksoverlays REF and ALT on the negative strand, because GLB1L lies there[1].
Replace YOUR_API_KEY with your own key to run the full example[1]:
from alphagenome.data import genome
from alphagenome.models.v2 import dna_client
from alphagenome.models.v2 import variant_scorers
from alphagenome.visualization import plot_components
dna_model = dna_client.create('YOUR_API_KEY')
# 1. Choose a condition: CD14-positive monocytes in blood.
condition = 'UBERON:0000178_CL:0001054'
# 2. Select a genomic region: center a 1 Mb interval on the variant.
variant = genome.Variant(
chromosome='chr2',
position=219243701,
reference_bases='C',
alternate_bases='T',
)
interval = variant.reference_interval.resize(dna_client.SEQUENCE_LENGTH_1MB)Using your own single-cell data
If you have human single-cell RNA-seq data, expression conditioning can replace a reference condition. The input is an AnnData object of raw integer UMI counts with Ensembl gene IDs in var_names. Each call accepts up to 256 cells, and the cell_condition_name label is written into the output metadata[1]. The output type becomes SC_GENE_EXPRESSION_DENOISED, which is denoised single-cell gene expression with one channel per strand in CPM[1][3]. Scoring uses RECOMMENDED_VARIANT_SCORERS['SC_GENE_EXPRESSION_DENOISED'], and plotting uses OverlaidGeneExpression, which can use a log scale[1].
How AlphaGenome 2 differs from AlphaGenome 1
Both versions come from the same package: alphagenome.models.v2 for AlphaGenome 2 and alphagenome.models.v1 for AlphaGenome 1[3]. The main differences are:
- New output types:
SC_GENE_EXPRESSION_DENOISED,SC_GENE_EXPRESSION,SC_ATAC,METHYLATIONandCELL_EMBEDDINGS[3]. PROCAPhas been removed; useCAGEfor transcription start site activity[3].SPLICE_SITESis now condition-specific, with 5 channels per condition:donor +,acceptor +,donor -,acceptor -andpadding .[3].- Variant scores have only a
raw_scorecolumn, with noquantile_score[3]. - Metadata lookups differ: AlphaGenome 1 uses
output_metadata(), while AlphaGenome 2 usessupported_conditions(), which has one row per condition, andobserved_metadata()for the measured tracks[3]. - Each track is labelled in
.metadata['imputation_mode']asobserved,imputed_supportedorimputed_exploratory, which separates measured values from imputed ones[3].
Limits and common questions
- Each call takes one condition. To compare several tissues or cell types, loop over them or use the batch arguments[1].
- With expression conditioning, a call accepts up to 256 cells[1].
- The input sequence can be up to 1 Mb[3].
- Code that still reads
quantile_scoremust change when you move to AlphaGenome 2, because that column is no longer produced[3]. - If your analysis used
PROCAP, switch toCAGEfor transcription start site activity[3].
Next steps
The official tutorials begin with choosing a condition and later cover conditioning on your own single-cell data. For end-to-end biological analyses, see the Vignettes. The user guide explains data objects, metadata and variant scoring[1].
Adapted from the AlphaGenome documentation by Google DeepMind[1], released under the CC-BY-4.0 license.
Sources
- 1Getting startedGoogle DeepMind AlphaGenome docs
- 2InstallationGoogle DeepMind AlphaGenome docs
- 3Migrating from AlphaGenome 1Google DeepMind AlphaGenome docs
Cite this page: Getting started with the AlphaGenome 2 API. TellWorld, https://www.tellworld.net/practice/practice-alphagenome-2-quickstart. Updated 2026-11-15