Raise a helpful error for VCS URLs in install()

CHANGELOG.md

@@ -6,6 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Changed
+
+- `install` now raises a helpful `ValueError` when given a VCS URL
+  (`git+`, `hg+`, `svn+`, `bzr+`) instead of an opaque parser error,
+  explaining that micropip only installs prebuilt wheels.
+  [#77](https://github.com/pyodide/micropip/issues/77)
+
 ## [0.11.1] - 2026/04/02
 
 ### Fixed

micropip/transaction.py

@@ -26,6 +26,12 @@
 
 logger = logging.getLogger("micropip")
 
+_VCS_URL_PREFIXES = ("git+", "hg+", "svn+", "bzr+")
+
+
+def _looks_like_vcs_url(req: str) -> bool:
+    return req.startswith(_VCS_URL_PREFIXES)
+
 
 @dataclass
 class Transaction:
@@ -77,6 +83,14 @@ async def add_requirement(self, req: str | Requirement) -> None:
         if isinstance(req, Requirement):
             return await self.add_requirement_inner(req)
 
+        if isinstance(req, str) and _looks_like_vcs_url(req):
+            raise ValueError(
+                f"Cannot install {req!r}: micropip only installs prebuilt wheels "
+                "and does not support installing from a VCS URL "
+                "(git+, hg+, svn+, bzr+). Provide a wheel URL or a package name "
+                "available on a configured index."
+            )
+
         try:
             as_req = constrain_requirement(Requirement(req), self.constrained_reqs)
 

tests/test_transaction.py

@@ -154,6 +154,25 @@ async def test_install_non_pure_python_wheel(host_compat_layer):
         await transaction.add_requirement(url)
 
 
+@pytest.mark.parametrize(
+    "url",
+    [
+        "git+https://github.com/example/example.git",
+        "git+https://github.com/example/example.git@v1.0.0",
+        "hg+https://example.com/repo",
+        "svn+https://example.com/repo",
+        "bzr+https://example.com/repo",
+    ],
+)
+@pytest.mark.asyncio
+async def test_add_requirement_vcs_url_helpful_error(url, host_compat_layer):
+    from micropip.transaction import Transaction
+
+    transaction = create_transaction(Transaction, host_compat_layer)
+    with pytest.raises(ValueError, match="does not support installing from a VCS URL"):
+        await transaction.add_requirement(url)
+
+
 def _pypi_metadata(package, versions_to_tags):
     # Build package release metadata as would be returned from
     # https://pypi.org/pypi/{pkgname}/json