Skip to content

Commit cddf104

Browse files
authored
Document build backend differences for local dependencies (#251)
- Clarify that UNIDEP_SKIP_LOCAL_DEPS is primarily needed for Hatchling projects - Explain that Setuptools automatically filters invalid file:// URLs - Add backend-specific behavior section showing the key difference: * Setuptools: Automatic filtering (environment variable not needed) * Hatchling: Includes all dependencies as specified (requires explicit filtering) - Provide context that this is a backend difference, not a UniDep limitation
1 parent acf423a commit cddf104

File tree

1 file changed

+8
-1
lines changed

1 file changed

+8
-1
lines changed

README.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -396,7 +396,12 @@ dependencies = [
396396

397397
#### `UNIDEP_SKIP_LOCAL_DEPS`
398398

399-
Local dependencies are useful for monorepos, shared configuration files, and local development workflows where you're developing multiple related packages. However, when building wheels for distribution (e.g., for PyPI), including local dependencies creates hardcoded `file://` paths in the wheel metadata, making wheels non-portable.
399+
Local dependencies are useful for monorepos, shared configuration files, and local development workflows where you're developing multiple related packages.
400+
However, when building wheels for distribution (e.g., for PyPI), including local dependencies can create hardcoded `file://` paths in the wheel metadata, making wheels non-portable.
401+
402+
**Build backend behavior differs:**
403+
- **Setuptools**: Automatically filters out invalid `file://` URLs during wheel building (this environment variable not needed)
404+
- **Hatchling**: Includes all dependencies as specified, requiring explicit filtering for distribution
400405

401406
Set this environment variable to skip including local dependencies as `file://` URLs when building distributable artifacts:
402407

@@ -414,6 +419,8 @@ UNIDEP_SKIP_LOCAL_DEPS=1 python -m build
414419
> [!NOTE]
415420
> When this variable is set, local dependencies are skipped but their actual dependencies (extracted from `requirements.yaml` or `pyproject.toml`) are still included in the built wheel. This ensures the wheel remains functional while avoiding non-portable absolute paths.
416421
>
422+
> **Backend-specific workaround**: This environment variable is primarily needed for Hatchling-based projects. Setuptools automatically handles this filtering, making wheels portable by default.
423+
>
417424
> **Two contexts, same codebase**: Local dependencies are included by default (great for `unidep install` during development), but this environment variable provides the context switch needed when building for distribution.
418425
419426
### Example packages

0 commit comments

Comments
 (0)