Quick Start

Why use soft-deps?

• For library authors: Provide optional features without forcing users to install heavy dependencies

• For users: Get full IDE support and autocomplete even for optional dependencies

• For teams: Graceful degradation with clear error messages instead of cryptic import failures

When to use soft-deps?

Use soft-deps when your library has optional features that depend on external packages:

• Data science libraries with optional visualization (matplotlib, plotly)

• Web frameworks with optional database drivers (psycopg2, pymongo)

• CLI tools with optional cloud integrations (boto3, google-cloud)

• Any library where you want some features to work without heavy dependencies

How it works:

Library authors use the soft-deps pattern in their code:

# your_library.py
from soft_deps.api import MissingDependency

# Try to import optional dependency
try:
    import pandas as pd
except ImportError:
    # Create helpful proxy if missing
    pd = MissingDependency("pandas", "pip install pandas")

def export_to_excel(data):
    """Export data to Excel file (requires pandas)."""
    # IDE gets full autocomplete here even if pandas not installed
    # Error only occurs when this line actually executes
    return pd.DataFrame(data).to_excel("output.xlsx")

Users get seamless experience regardless of what’s installed:

# user_script.py
from your_library import export_to_excel

# This imports successfully even without pandas installed
# IDE provides full autocomplete and type hints

try:
    export_to_excel({"col1": [1, 2, 3]})
except ImportError as e:
    print(e)  # "To use `pandas.DataFrame`, pip install pandas."

The difference:

# ❌ Traditional approach - breaks immediately
import pandas as pd  # ImportError if not installed

# ❌ Lazy imports - no IDE support
def export_data():
    import pandas as pd  # IDE can't help with autocomplete

# ✅ soft-deps - best of both worlds
try:
    import pandas as pd
except ImportError:
    pd = MissingDependency("pandas", "pip install pandas")
# IDE gets full support, graceful errors when actually used

Recommended Layout

Put every optional import in one module, and import the names from there. The installation hint can point at the extra that brings the dependency in:

# your_library/importer.py
from soft_deps.api import MissingDependency

try:
    import pandas as pd
except ImportError:
    pd = MissingDependency("pandas", "pip install your_library[excel]")

try:
    import boto3
except ImportError:
    boto3 = MissingDependency("boto3", "pip install your_library[aws]")

# your_library/excel.py
from .importer import pd

def export_to_excel(data: dict, path: str) -> pd.DataFrame:
    df = pd.DataFrame(data)
    df.to_excel(path)
    return df

The rule is simple: use the dependency inside functions, not at module level. Then importing your_library.excel always works, and only calling export_to_excel() without pandas raises an ImportError.

What Raises and What Does Not

Only real use of the missing dependency raises an ImportError. Merely mentioning it does not, so type hints work with or without from __future__ import annotations:

The error message names what was used, for example To use `pandas.DataFrame`, pip install your_library[excel].

Keep these out of module level, because they run while the module is imported:

• decorators from the dependency, such as @numba.jit;

• classes that subclass something from the dependency, such as class MyModel(pydantic.BaseModel);

• module-level calls, such as session = boto3.Session().

Put such code in a module that only the optional feature imports.

Install

soft_deps is released on PyPI, so all you need is to:

$ pip install soft-deps

To upgrade to latest version:

$ pip install --upgrade soft-deps

Use with AI Coding Agents

This repo ships an Agent Skill that documents the public API of soft_deps, so an AI coding agent such as Claude Code can use the library without reading its source. It lives in .claude/skills/pypi-soft_deps. To use it in your project, copy it into your project’s .claude/skills/ folder. Run this from your project’s root:

$ git clone --depth 1 https://github.com/MacHu-GWU/soft_deps-project.git /tmp/soft_deps-project
$ mkdir -p .claude/skills
$ cp -R /tmp/soft_deps-project/.claude/skills/pypi-soft_deps .claude/skills/