unearth

What it is and what it does

Unearth is a library for finding and downloading Python packages from package indexes. It extracts and stabilizes the core package-finding logic, offering a documented, versioned API that downstream projects can rely on. It works alongside other low-level package-management tools to form a complete package-management toolkit.

You use it either as a Python library—instantiating a PackageFinder with index URLs and calling find_best_match() to locate a package that satisfies a requirement—or via its CLI to query indexes and inspect matching distributions. It returns structured metadata about candidates, including version, download URL, Python version requirements, and metadata links.

Use it for:

• Build a custom package manager or installer that needs stable package discovery without relying on pip's internal APIs.
• Query a private or custom PyPI-compatible index to find the best match for a requirement in an automated workflow.
• Inspect available versions and metadata for a package before deciding which to download.
• Integrate package finding into a tool that needs to locate distributions independently.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Finds and downloads Python packages from package indexes by matching requirements, providing a stable library API for package discovery.

Yes. Unearth is actively maintained, has no known vulnerabilities, low install friction, and fills a genuine gap by providing a stable, versioned API for package discovery. It is well-suited for anyone building package-management tools or workflows that need reliable access to package indexes.

Install

unearth on PyPI

pip install unearth

uv add unearth

poetry add unearth

Installing unearth

Before you install

Active maintenance with a recent release and low install friction—only two runtime dependencies (packaging and httpx). Supports Python 3.9 onward.

License in practice

MIT license permits commercial and private use with minimal restrictions, making it suitable for integration into other tools.

Quickstart

from unearth import PackageFinder
finder = PackageFinder(index_urls=["https://pypi.org/simple/"])
result = finder.find_best_match("flask>=2")
print(result.best)

Requires Python >=3.9

Verify before relying

• Whether the package finder respects all PyPI-compatible index formats and authentication schemes beyond basic HTTP.
• Performance characteristics when querying large indexes or handling thousands of package candidates.
• Stability guarantees and backward-compatibility policy beyond semantic versioning claims in the description.

Package facts

Evidence: unearth-0.18.3-py3-none-any.whl

Tags

More Build Tools packages