Registry / ai-ml / pyhmmer

pyhmmer

JSON →
library0.12.3pypypi✓ verified 26d ago

pyhmmer provides high-performance Cython bindings and a Pythonic interface to the HMMER3 C library, enabling powerful sequence analysis using Hidden Markov Models. It is used for searching protein and nucleic acid sequence databases, identifying remote homologs, and building profile HMMs. The current stable version is 0.12.0, with a release cadence of several minor versions per year, indicating active development.

pip install pyhmmer
INSTALL
IMPORT
SIG · PYHMMER
P
pyhmmer
ai-mlpythonv0.12.3
Install
2.1s avg
Import
206ms
Disk
30MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.12.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
build_error
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.1s · import 0.206s · 32MB
30MB installed
● package 30MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Alphabet
from pyhmmer.easel import Alphabet
Sequence
from pyhmmer.easel import Sequence
HMM
from pyhmmer.hmm import HMM
Pipeline
from pyhmmer.pipeliner import Pipeline
HMMFile
from pyhmmer.plan7 import HMMFile

This quickstart demonstrates how to create a simple HMM from a sequence, define target sequences, and perform a basic HMMER search using `pyhmmer.pipeliner.Pipeline`. It then iterates through the search results to display hits and their associated domains. Note that sequence names and data must be bytes.

import pyhmmer from pyhmmer.easel import Alphabet, Sequence from pyhmmer.hmm import HMM from pyhmmer.pipeliner import Pipeline # 1. Define the alphabet for sequences and HMMs alphabet = Alphabet.amino() # 2. Create a simple HMM from a seed sequence (or load from .hmm file) # For a real application, you would typically load an HMM from a file # using `pyhmmer.plan7.HMMFile('your_file.hmm').read_one()` seed_sequence = Sequence(name=b"seed_seq", sequence=b"AGILRVAG") hmm = HMM.from_sequence(seed_sequence, alphabet) hmm.name = b"my_simple_hmm" # 3. Create target sequences to search against target_sequences = [ Sequence(name=b"target1", sequence=b"AGILRVAGGPPPL"), Sequence(name=b"target2", sequence=b"GPPPLGGAGILRV"), Sequence(name=b"target3", sequence=b"XXXXXAGILRVXXXX") # Contains mismatching chars ] # 4. Initialize the HMMER pipeline # The pipeline manages memory and resources for the search process pipeline = Pipeline(alphabet) # 5. Run the search: search the HMM against the target sequences # This method returns a pyhmmer.search.SearchResult object results = pipeline.search_hmm(hmm, target_sequences) # 6. Process and print the results found_hits = False for hit in results.hits: found_hits = True print(f"\n--- Hit Found ---") print(f"Query HMM: {hit.query_name.decode()}") print(f"Target Sequence: {hit.target_name.decode()}") print(f" E-value: {hit.evalue:.2e}, Bit Score: {hit.score:.2f}") for dom in hit.domains: print(f" Domain: Query {dom.query_start}-{dom.query_end} (HMM positions)") print(f" Target {dom.target_start}-{dom.target_end} (Sequence positions)") if not found_hits: print("No significant hits found for the HMM against target sequences.")
Debug
Known issues
gotchapyhmmer is a wrapper around the HMMER3 C library. While `pip install pyhmmer` attempts to download and compile HMMER3 from source, this process can fail if necessary system build tools (like a C compiler, e.g., gcc/clang, and development libraries) are not installed or correctly configured on your system.
fix
Ensure you have a C compiler and build essentials installed (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS). For more robust HMMER3 dependency management, especially on Windows or complex environments, consider installing `pyhmmer` via Bioconda (`conda install -c bioconda pyhmmer`). If HMMER3 is installed manually, set the `HMMER_DIR` environment variable to its installation prefix before building pyhmmer.
affects: All versions
breakingAs a 0.x series library, `pyhmmer`'s API is still evolving and is subject to changes between minor versions (e.g., 0.10.x to 0.11.x, or 0.11.x to 0.12.x). This can include renaming of classes, methods, changes in function signatures, or modifications to the structure of result objects, potentially breaking existing code without a deprecation warning.
fix
Always review the changelog and migration guides (if available) when upgrading `pyhmmer` across minor versions. Test your code thoroughly after any upgrade. Pin your `pyhmmer` version in `requirements.txt` to avoid unexpected breakage in production environments.
affects: <0.12.0
gotchaHMMER operations, especially with large HMM databases or extensive sequence queries, can be highly memory-intensive due to the underlying C library. Insufficient RAM can lead to crashes or degraded performance. While `pyhmmer` manages C memory, improper handling of objects or large batch sizes can exacerbate memory pressure.
fix
Monitor memory usage for your specific workloads. For very large datasets, consider processing sequences in batches rather than loading everything into memory at once. Ensure `pyhmmer.pipeliner.Pipeline` and other resource-heavy objects are properly scoped (e.g., within functions or with explicit `del` if not garbage collected quickly enough) to allow for memory cleanup.
affects: All versions
gotchaThe `pyhmmer` library operates with specific `Alphabet` types (amino, DNA, RNA). Mismatching the alphabet between an HMM and the sequences being searched will lead to incorrect results or runtime errors. Additionally, sequence data (`Sequence.sequence` and `Sequence.name`) must be provided as `bytes`, not strings.
fix
Explicitly define and pass the correct `Alphabet` (e.g., `Alphabet.amino()`, `Alphabet.dna()`) to all relevant `pyhmmer` objects, ensuring consistency. Always encode sequence data and names to `bytes` before passing them to `pyhmmer.easel.Sequence` or similar constructors.
affects: All versions
Errors
Common errors & fixes
AttributeError: 'pyhmmer.plan7.TopHits' object has no attribute 'query_accession'
This error occurs when using an older API method to access attributes like 'query_accession' or 'query_name' from `pyhmmer.plan7.TopHits` objects in newer versions of pyhmmer, as the API for accessing these attributes has changed.
fix
Access the required information directly from the `Hit` object within `TopHits` by iterating or indexing, for example, `top_hits[0].name` or `hit.name` after iterating through `top_hits`.
PyHMMER installation on Windows fails or is not supported
pyhmmer relies on the HMMER3 C library, which does not support Windows natively, making direct installation of pyhmmer on Windows impossible.
fix
Install pyhmmer within a Windows Subsystem for Linux (WSL) environment, use a Linux virtual machine, or a Docker container.
ValueError: Could not determine format of file: '/path/to/your/file'
This error typically arises when pyhmmer cannot correctly identify the format of the input file (e.g., an HMM database or a sequence file), or if the file path is incorrect or the file is corrupted.
fix
Ensure the file path is correct, the file exists, and its content is in a supported HMMER3 or sequence format (e.g., FASTA for sequences, HMM for HMM profiles). Check for file corruption and specify the file format explicitly if the automatic detection fails.
pyhmmer.errors.AlphabetMismatch: A value error caused by an alphabet mismatch.
This error occurs when an HMM and the sequences being searched or processed have incompatible biological alphabets (e.g., trying to search protein sequences with a DNA HMM or vice-versa).
fix
Ensure that the alphabet of the HMM matches the alphabet of the sequences you are providing. You may need to specify the correct alphabet when creating or loading `pyhmmer.easel.Alphabet` objects.
hmmsearch yields <generator object ...> instead of TopHits object
The `pyhmmer.hmmer.hmmsearch` function returns a generator that yields `TopHits` objects, rather than directly returning a single `TopHits` object. Users expecting a direct `TopHits` object might be surprised by the generator.
fix
Iterate over the generator to process each `TopHits` object, or convert the generator to a list if all results are needed in memory (e.g., `list(pyhmmer.hmmer.hmmsearch(hmms, seqs))`).
Upgrade
Version history
0.12.3latest on PyPI · released Aug 19, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources
pyhmmer — pip install pyhmmer · libregistry