Install & Compatibility
Where this runs
tested against v0.18.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.360s · 23.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.350s · 24MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PackageFinder
✓ from unearth import PackageFinder
✗ from unearth import Unearth
Link
✓ from unearth import Link
Package
✓ from unearth import Package
This example demonstrates how to initialize `Unearth` and use it to find the best match for a Python package from PyPI, using a temporary cache directory.
import tempfile
from pathlib import Path
from unearth import Unearth
# Create a temporary directory for caching resolved packages
with tempfile.TemporaryDirectory() as cache_dir_str:
cache_dir = Path(cache_dir_str)
# Instantiate Unearth to search for packages on PyPI
finder = Unearth(
index_urls=["https://pypi.org/simple"],
cache_dir=cache_dir
)
# Find matches for a specific package, e.g., 'requests'
matches = finder.find_matches("requests")
# Get the best matching distribution
best_match = matches.best_match
if best_match:
print(f"Found best match: {best_match.name} {best_match.version} from {best_match.link.url}")
# To actually download, you would process best_match.link.url
# Unearth primarily provides the links, not direct download functionality
else:
print("No matches found for requests.")
unearth --version
Debug
Known issues
breakingUnearth dropped support for Python 3.8 in version 0.18.0. Earlier, Python 3.7 and below were dropped in version 0.17.2. Users on affected Python versions will encounter errors.fixEnsure your Python environment is 3.9 or newer. If you must use Python 3.8, pin `unearth<0.18.0`. For Python 3.7 or older, pin `unearth<0.17.2`.
affects: <0.18.0 (for 3.8), <0.17.2 (for <=3.7)
gotchaHandling of Git URLs, especially with branches and specific revisions, has been refined across several versions. A regression in earlier 0.18.x versions might have prevented correct parsing of Git URLs with branches.fixAlways use the latest `unearth` version (0.18.2+) to ensure robust and correct parsing and fetching from Git URLs that include branches or specific commit references.
affects: <0.18.2 (for branches), <0.18.0 (for refs)
gotchaStarting from version 0.17.0, `unearth` became more explicit with warnings related to parsing `.netrc` files. Users might see warnings if their `.netrc` is malformed, has incorrect permissions, or if authentication fails.fixVerify that your `.netrc` file is correctly formatted and has appropriate file permissions (e.g., `chmod 600 ~/.netrc`). Warnings were made less verbose in 0.17.1 and 0.17.2.
affects: 0.17.0+
Upgrade
Version history
0.18.3latest on PyPI · released Aug 14, 2026
Audit
Dependencies
No dependency data recorded yet.