Linkify-it-py: Unicode-aware Link Recognition

Common errors

• ModuleNotFoundError: No module named 'linkify_it'

  cause The `linkify-it-py` package was installed, but the import statement used an incorrect module name, such as `linkify-it-py` or `linkify_it_py`, instead of the correct `linkify_it`.
  fix Correct the import statement to `from linkify_it import LinkifyIt`.

• ModuleNotFoundError: Linkify enabled but not installed.

  cause This error occurs when using a dependent library like `markdown-it-py` or `myst-parser` with its linkify functionality enabled, but the `linkify-it-py` library, which provides this feature, has not been installed in the environment.
  fix Install the `linkify-it-py` library using pip: `pip install linkify-it-py`.

• AttributeError: 'LinkifyIt' object has no attribute 'some_non_existent_method'

  cause The user is attempting to call a method that does not exist on the `LinkifyIt` instance, likely due to a misunderstanding of the library's API. For example, trying to call `linkify.find_links()` instead of the correct `linkify.match()` or `linkify.test()`.
  fix Refer to the `linkify-it-py` official documentation and use the correct methods provided by the `LinkifyIt` object, such as `linkify.match(text)` to retrieve matches or `linkify.test(text)` for a boolean check.

Warnings

• breaking Version 2.0.0 introduced significant changes, including the addition of `matchAtStart` and fixes for paired symbols. While not all API changes were explicitly marked as breaking in `linkify-it-py`'s changelog, a major version bump indicates potential behavioral shifts that may affect applications relying on specific older parsing behaviors. Reviewing release notes is advised for upgrades from `v1.x.x`.
  Fix: Thoroughly test existing linkification logic after upgrading to `v2.x.x`. Pay attention to how punctuation and boundary conditions are handled, especially if your application relied on specific behaviors in `v1.x.x`.
• gotcha The library explicitly requires Python 3.10 or higher. Attempting to install or run `linkify-it-py` on older Python versions (e.g., 3.9 or earlier) will result in installation failures or runtime errors due to `Requires-Python` metadata.
  Fix: Ensure your project's Python environment is 3.10 or newer before installing `linkify-it-py`. Upgrade your Python interpreter if necessary.
• gotcha By default, `LinkifyIt()` is initialized with predefined schemas for `http(s)://`, `ftp://`, `mailto:`, `//` (protocol-neutral), as well as 'fuzzy' links (like `example.com`) and email addresses. Users sometimes mistakenly try to re-add these default schemas, which is unnecessary and can lead to unexpected behavior if custom rules conflict.
  Fix: Consult the documentation to understand the default schemas and options. Use `add()` method only for new, custom schemas or to override/disable existing ones. For example, `linkify.add('ftp:', None)` disables the FTP protocol.

Install

• pip install linkify-it-py Install stable version

Imports

• LinkifyIt

  from linkify_it import LinkifyIt

Quickstart

This quickstart demonstrates basic linkification using `LinkifyIt` with default settings, showing how to test for and extract link matches. It also includes an example of customizing the linkifier by adding TLDs, protocol aliases, and enabling fuzzy IP detection.

from linkify_it import LinkifyIt

# Initialize linkifier with default schemas (http, https, ftp, mailto, fuzzy links)
linkify = LinkifyIt()

text1 = "Visit our site: github.com!"
matches1 = linkify.match(text1)
print(f"Text: '{text1}'")
for match in matches1:
    print(f"  Matched: '{match.raw}' at index {match.index}-{match.last_index}, URL: {match.url}")

text2 = "Email me at user@example.com or check //example.net/path"
matches2 = linkify.match(text2)
print(f"\nText: '{text2}'")
for match in matches2:
    print(f"  Matched: '{match.raw}' at index {match.index}-{match.last_index}, URL: {match.url}")

# Example with custom options
from linkify_it.tlds import TLDS
linkify_custom = (
    LinkifyIt()
    .tlds(TLDS) # Reload with full official TLDs list
    .tlds("onion", True) # Add unofficial .onion domain
    .add("git:", "http:") # Treat 'git:' as an alias for 'http:'
    .set({"fuzzy_ip": True}) # Enable IPs in fuzzy links (without schema)
)

text3 = "Check out git:repo.git or a fuzzy IP 192.168.1.1/admin"
matches3 = linkify_custom.match(text3)
print(f"\nText: '{text3}' (custom linkify)")
for match in matches3:
    print(f"  Matched: '{match.raw}' at index {match.index}-{match.last_index}, URL: {match.url}")