BD003: InstallSucceeds

Overview

Property Value
ID BD003
Name InstallSucceeds
Group build
Severity ERROR

Description

Verifies that the package installs successfully in a clean virtual environment.

This check is critical because:

  • It tests the user’s installation experience
  • It catches undeclared dependencies
  • It verifies the package works outside your development environment
  • It detects issues that only appear in fresh installs

What it checks

The check creates a temporary virtual environment, builds a wheel, and installs it:

  • PASSED: Package installs successfully with all dependencies
  • FAILED: Installation fails (reports pip error)
  • NOT_APPLICABLE: No pyproject.toml found or build package not installed

How to fix

Run installation test locally

# Create a fresh virtual environment
python -m venv test-env
source test-env/bin/activate  # or test-env\Scripts\activate on Windows

# Build and install
python -m build --wheel
pip install dist/*.whl

# Clean up
deactivate
rm -rf test-env

Common failure causes

  1. Missing dependencies: Dependencies not listed in pyproject.toml
  2. Invalid dependency specifiers: Syntax errors in version constraints
  3. Unavailable packages: Dependencies not on PyPI
  4. Conflicting dependencies: Version conflicts between requirements
  5. Platform-specific issues: Dependencies not available on all platforms

Declare dependencies correctly

In pyproject.toml:

[project]
dependencies = [
    "requests>=2.28.0",
    "click>=8.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "mypy>=1.0.0",
]

Check dependency resolution

Use pip-tools or uv to verify dependencies resolve:

# With uv
uv pip compile pyproject.toml

# With pip-tools
pip-compile pyproject.toml

Test in isolated environment

For thorough testing:

# Using tox
tox -e py312

# Using nox
nox -s tests

Why ERROR severity?

This check is an ERROR because:

  • Users cannot use your package if installation fails
  • Installation failures are frustrating and reflect poorly on package quality
  • Undeclared dependencies cause runtime errors

Configuration

Timeout

The default timeout is 600 seconds (10 minutes). For packages with many dependencies:

[tool.pycmdcheck.checks.BD003]
timeout = 900  # 15 minutes

Skip this check

[tool.pycmdcheck]
skip = ["BD003"]

For faster local development, skip slow build checks:

[tool.pycmdcheck]
skip_groups = ["build"]

CLI

pycmdcheck --skip BD003
# or skip all build checks
pycmdcheck --skip-group build