{"id":9717,"library":"edlib","title":"Edlib - Sequence Alignment","description":"Edlib is a lightweight and super-fast C/C++ library for sequence alignment using various edit (Levenshtein) distance algorithms, with official Python bindings. It supports global, semi-global, and local alignment modes and can return distance, locations, or even the full alignment path. The current version is 1.3.9.post1, with releases typically driven by bug fixes and minor improvements rather than a strict schedule.","status":"active","version":"1.3.9.post1","language":"en","source_language":"en","source_url":"https://github.com/Martinsos/edlib","tags":["sequence alignment","edit distance","Levenshtein","bioinformatics","string matching"],"install":[{"cmd":"pip install edlib","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary `align` function is accessed directly from the `edlib` module, not as a top-level import.","wrong":"from edlib import align","symbol":"align","correct":"import edlib\nedlib.align(...)"}],"quickstart":{"code":"import edlib\n\n# Global alignment (Needleman-Wunsch-like)\nresult = edlib.align(\"apple\", \"aple\", mode=\"NW\", task=\"distance\")\nprint(f\"NW Distance: {result['editDistance']}\")\n\n# Semi-global alignment (ends don't cost)\nresult = edlib.align(\"apple\", \"pple\", mode=\"SHW\", task=\"distance\")\nprint(f\"SHW Distance: {result['editDistance']}\")\n\n# Global alignment with path (more computationally intensive)\nresult = edlib.align(\"apple\", \"apply\", mode=\"NW\", task=\"path\")\nprint(f\"NW Distance with path: {result['editDistance']}\")\nprint(f\"Alignment path: {result['alignment']}\")\n","lang":"python","description":"This quickstart demonstrates how to use `edlib.align()` for basic sequence alignment, showing different `mode` and `task` parameters to get either the edit distance or the full alignment path."},"warnings":[{"fix":"Upgrade to edlib >= 1.2.7 or ensure your input sequences don't trigger this specific edge case in older versions.","message":"Older versions (pre-1.2.7) could freeze or exhibit incorrect behavior when the input alphabet was exactly 256 unique characters. While fixed, be mindful of extremely large or unusual character sets in older installations.","severity":"gotcha","affected_versions":"<1.2.7"},{"fix":"Use `edlib.align(seq1, seq2, task='distance')` if you only need the numerical edit distance.","message":"When only the edit distance is needed, explicitly set `task='distance'` for optimal performance. Using `task='locations'` or `task='path'` involves additional computation to traceback the alignment, which is slower.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to edlib >= 1.2.5. If stuck on an older version, pre-validate inputs to ensure sequences are non-empty.","message":"Providing empty strings as query or target sequences in versions prior to 1.2.5 could lead to incorrect results or crashes. Modern versions handle this correctly.","severity":"gotcha","affected_versions":"<1.2.5"},{"fix":"Carefully choose `k` based on expected edit distances. If a solution is expected but not found, try increasing `k` or removing it (for unlimited distance).","message":"Setting the `k` parameter (maximum edit distance) too aggressively low might result in `no solution found` even if a solution exists with a slightly higher distance. This was particularly buggy in v1.1.1 but is still a design consideration.","severity":"gotcha","affected_versions":"All versions, especially <1.1.2"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure your query and target sequences are standard Python strings. Decode byte strings if necessary, e.g., `seq.decode('utf-8')`.","cause":"You are passing byte strings (`bytes`) instead of Unicode strings (`str`) to `edlib.align()`.","error":"TypeError: argument 1 must be str, not bytes"},{"fix":"Ensure both the query and target sequences passed to `edlib.align()` are non-empty strings. If using an older version of edlib (<1.2.5), consider upgrading.","cause":"You are attempting to align one or more empty strings, which earlier versions of edlib did not handle gracefully, or it's a validation error in more recent versions when explicit validation is enabled.","error":"ValueError: Query and target sequences must be non-empty."},{"fix":"Increase the `k` parameter, or remove it entirely if you want to find an alignment regardless of distance. Ensure you are using a recent version of edlib to avoid known internal bugs.","cause":"This typically occurs when the `k` parameter (maximum edit distance) is set too low for the given sequences, meaning no alignment with `editDistance <= k` could be found. It can also occur in very rare edge cases due to internal bugs in older versions (e.g., v1.1.1).","error":"RuntimeError: no solution found"},{"fix":"Upgrade your `edlib` installation to version 1.2.7 or newer. If upgrading isn't an option, avoid input sequences with an exact 256-character alphabet.","cause":"In versions prior to 1.2.7, edlib had a bug that could cause it to freeze when input sequences contained an alphabet of exactly 256 unique characters.","error":"The program freezes or hangs indefinitely when calling `edlib.align()`."}]}