Skip to main content

PyEnsembl

Tests Coverage PyPI

PyEnsembl looks up genes, transcripts, exons and their protein and transcript sequences in a pinned Ensembl release or in your own GTF and FASTA files. It downloads and indexes an annotation once; after that, queries run locally. It is the gene annotation layer of the OpenVax tools: Varcode, Isovar, Topiary and Vaxrank use it, and it builds on datacache for downloads and gtfparse for reading GTF files.

Install

Use Python 3.11 or later. Install the package and one annotation release:

python -m pip install pyensembl
pyensembl install --release 93 --species human

The second command selects human GRCh38 and downloads and indexes Ensembl release 93's annotation, transcript and protein files, about 1.3 GB. It takes several minutes. Whole-genome DNA is a separate, optional download.

Quick start

After installing the data above:

from pyensembl import EnsemblRelease

with EnsemblRelease(93, species="human") as data:
    gene = data.gene_by_id("ENSG00000141510")
    print(gene.name, gene.contig, gene.start, gene.end, gene.strand)
    transcript = data.transcript_by_id("ENST00000269305")
    print(transcript.name, transcript.protein_sequence[:30])
TP53 17 7661779 7687550 -
TP53-201 MEEPQSDPSVEPPLSQETFSDLWKLLPENN

Coordinates are one-based and inclusive; TP53 is on the minus strand. Pin the release you analyze: coordinates, IDs and sequences can change between releases. A gene name can match several loci, so data.genes_by_name("TP53") returns a list.

Command line

The pyensembl command installs and manages local data:

pyensembl install --release 93 --species human  # download and index a release
pyensembl list                                  # installed genomes and their status
pyensembl inspect --release 93                  # files, sizes and provenance, offline
pyensembl available                             # supported species, assemblies and releases
pyensembl delete-all-files --release 93         # remove one release's local data
pyensembl prune --dry-run                       # shared reference DNA that no release uses

The command-line reference lists every option. For Tab completion, run activate-global-python-argcomplete once, or add eval "$(register-python-argcomplete pyensembl)" to your shell's startup file.

Documentation

The documentation starts with installation and a first lookup, then covers one task per page. In reading order:

  1. Find genes and transcripts by name, ID, position or biotype.
  2. Get protein and transcript sequences, coding sequences, UTRs and exons.
  3. Read genomic DNA for introns and flanking sequence.
  4. Choose a reference: species, assembly, and numbered or dated Ensembl releases.
  5. Install and manage data from Python, check what is installed and free disk space.
  6. Use your own annotations from GTF and FASTA files.

Also see gene name aliases, genetic codes and the API reference.

Development

From a clone of this repository:

python -m pip install -e '.[dev]'
./lint.sh   # ruff and mypy
./test.sh   # pytest with coverage
./docs.sh   # strict docs build and link checks; needs '.[docs]'

Most tests need the Ensembl releases that the Tests workflow installs. Every PR bumps pyensembl/version.py, including documentation changes. See contributing and releasing.

License

Apache License 2.0

Metadata

Release files for pyensembl 2.34.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyensembl 2.34.1
File Size Uploaded Provenance Actions
pyensembl-2.34.1.tar.gz 529.3 kB Without provenance Details for pyensembl-2.34.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyensembl 2.34.1
File Interpreter ABI Platform Actions
pyensembl-2.34.1-py3-none-any.whl Python 3 none any Details for pyensembl-2.34.1-py3-none-any.whl

Total release size: 702.9 kB

Release files / pyensembl-2.34.1.tar.gz

Download URL pyensembl-2.34.1.tar.gz
Size 529.3 kB
Tags Source
SHA-256 checksum
How to use checksums
3fa034bb1c71713d3e0bdfedef553bef90c03d0f00feb4e16250848a0ca14af9
BLAKE2b-256 checksum
How to use checksums
43953b2052bb3e1be74311e303729e83f3700f06381a27c64a94514bd1285878
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Release files / pyensembl-2.34.1-py3-none-any.whl

Download URL pyensembl-2.34.1-py3-none-any.whl
Size 173.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
12a845d499b9d65c0ec3ff5836c6b6fabe0c5cbf3782b3da8a79d750f54d4446
BLAKE2b-256 checksum
How to use checksums
78ed71cbfbd3c510f5d00269b6d018efa30fbb38f88cf8a35bf5da7e82c3686b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Security for pyensembl 2.34.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.34.1 This release

2 release files No provenance

0.3

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page