---
id: unearth
version: "0.18.3"
license: MIT
license_treatment: permissive
maintenance: active
---

# unearth — A utility to fetch and download python packages

License: permissive · Maintenance: active · Downloads: 11.9M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 11.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python package finder, download packages from pypi, package index search, fetch python distributions, package discovery library, find best package match, pypi package locator, package-management, pypi-client

[View on SkillFed](https://skillfed.io/packages/unearth) · [View on PyPI](https://pypi.org/project/unearth/)