What causes "Can't add %r to environment" in pypa/pip?

If adding a single distribution, use `env.add(dist)` instead of `env += dist` (only `+=` is type-restricted; add() takes a Distribution).

pypa/pip · error · TypeError

Can't add %r to environment

Error message

Can't add %r to environment

What it means

Raised by Environment.__iadd__ (the += operator) when the right-hand operand is neither a Distribution nor an Environment. Environment is a dict-like collection of project_name -> list[Distribution]; it only knows how to merge in another whole environment or a single distribution. Any other type (str, Requirement, list, tuple) is rejected.

Source

Thrown at src/pip/_vendor/pkg_resources/__init__.py:1308

        to the `installer` argument."""
        return installer(requirement) if installer else None

    def __iter__(self) -> Iterator[str]:
        """Yield the unique project names of the available distributions"""
        for key in self._distmap.keys():
            if self[key]:
                yield key

    def __iadd__(self, other: Distribution | Environment):
        """In-place addition of a distribution or environment"""
        if isinstance(other, Distribution):
            self.add(other)
        elif isinstance(other, Environment):
            for project in other:
                for dist in other[project]:
                    self.add(dist)
        else:
            raise TypeError("Can't add %r to environment" % (other,))
        return self

    def __add__(self, other: Distribution | Environment):
        """Add an environment or distribution to an environment"""
        new = self.__class__([], platform=None, python=None)
        for env in self, other:
            new += env
        return new


# XXX backward compatibility
AvailableDistributions = Environment


class ExtractionError(RuntimeError):
    """An error occurred extracting a resource

    The following attributes are available from instances of this exception:

View on GitHub (pinned to d7d0d0a394)

Solutions

If adding a single distribution, use `env.add(dist)` instead of `env += dist` (only `+=` is type-restricted; add() takes a Distribution).
If adding multiple, loop: `for d in dists: env.add(d)` or merge a second Environment built from them.
Pass an Environment instance on the right side of += (e.g. `env1 += env2`).

Example fix

// before
env += [dist_a, dist_b]   # TypeError: Can't add [...] to environment

// after
for d in (dist_a, dist_b):
    env.add(d)

Defensive patterns

Strategy: type-guard

Validate before calling

from pkg_resources import Environment, Distribution

def safe_iadd(env, other):
    if isinstance(other, Distribution):
        env.add(other)
    elif isinstance(other, Environment):
        env += other
    else:
        raise TypeError('Can only add Distribution or Environment, got %r' % type(other))
    return env

Type guard

from pkg_resources import Environment, Distribution

def is_env_addable(x):
    return isinstance(x, (Distribution, Environment))

Try / catch

try:
    env += other
except TypeError as e:
    if 'Can\'t add' in str(e):
        # coerce or report
        raise
    raise

Prevention

Use env.add(dist) for single distributions instead of +=.
Build a second Environment and merge with += for bulk adds.
Never pass Requirements, strings, or lists to Environment via +=.

When it happens

Trigger: Writing `env += obj` or calling `env.__iadd__(obj)` where obj is a Requirement, a project-name string, a list of distributions, or any non-Distribution/non-Environment object.

Common situations: Treating Environment like a flat list and trying to `+= [dist1, dist2]` or `+= some_requirement`. Also confusing it with working_set.add(), which does accept a Distribution (but not arbitrary objects either).

Related errors

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/a508e58fbe87642c.json. Report an issue: GitHub.