---
id: pyensembl
version: "2.10.4"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# pyensembl — Python interface to Ensembl reference genome metadata

License: permissive · Maintenance: active · Downloads: 104.2K/mo

## What it is and what it does

PyEnsembl is a Python library that wraps Ensembl reference genome data—exons, transcripts, genes, and their chromosomal locations—making it queryable through a Python API. It downloads GTF (gene transfer format) and FASTA sequence files from the Ensembl FTP server, indexes them into a local database, and exposes methods to look up genes by name or ID, find transcripts, retrieve exon coordinates, and query genomic features at specific loci. It also supports custom genomes loaded from user-supplied GTF and FASTA files or remote URLs.

The package is designed for bioinformatics workflows where you need to resolve gene names to genomic coordinates, retrieve transcript structures, or annotate genomic variants against a reference. It handles the download and caching automatically and stores data in a platform-specific cache directory (configurable via environment variable). The API provides many query methods—by gene ID, gene name, transcript ID, exon ID, chromosomal position, and strand—returning Gene, Transcript, and Exon objects with associated metadata.

Use it for:

- Annotate genomic variants (SNPs, indels) by looking up overlapping genes and transcripts at their genomic coordinates.
- Retrieve transcript structures and exon boundaries for a given gene name to design primers or analyze splicing.
- Build a local reference database for a specific Ensembl release and species to support reproducible bioinformatics pipelines.
- Query the nearest gene to a genomic position when no gene directly overlaps, useful for intergenic variant classification.
- Load and index custom genome annotations (non-Ensembl GTF/FASTA) for organisms or assemblies not in the Ensembl repository.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

PyEnsembl provides a Python interface to query Ensembl reference genome metadata—genes, transcripts, exons, and their genomic coordinates—by downloading GTF and FASTA files and indexing them locally or loading custom genome data.

Yes. PyEnsembl is actively maintained, has low install friction, carries no known vulnerabilities, and is the standard tool for programmatic access to Ensembl genome metadata in Python. Install it if you need to query genes, transcripts, or exons by name or genomic position in a bioinformatics workflow. The main gotcha is the separate data-download step required before first use.

## Install

pip install pyensembl
uv add pyensembl
poetry add pyensembl

## Installing pyensembl

Before you install: Low friction: pure Python wheel with 7 runtime dependencies (datacache, gtfparse, numpy, and others). Marked active with a release 37 days ago. Requires Python 3.9 or later and a separate download step (`pyensembl install`) to fetch genome data before first use.

License in practice: Apache-2.0 (permissive): you may use, modify, and distribute this package freely in commercial and private projects, provided you include a copy of the license and state any changes made.

Quickstart:

pip install pyensembl

from pyensembl import EnsemblRelease
data = EnsemblRelease(77)
gene_names = data.gene_names_at_locus(contig=6, position=29945884)

Requires Python 3.9 or later. Before first use, run `pyensembl install --release <N> --species <name>` to download and index genome data.

Verify before relying:

- Whether datacache, gtfparse, and other dependencies are actively maintained and free of known vulnerabilities.
- Performance characteristics when querying large genomes or handling non-Ensembl GTF formats (documentation notes this is still in development).

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 104.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ensembl genome reference data python, query genes transcripts exons, genomic annotation lookup, gtf fasta genome parser, reference genome metadata api, bioinformatics, genomics, reference-data

[View on SkillFed](https://skillfed.io/packages/pyensembl) · [View on PyPI](https://pypi.org/project/pyensembl/)