python-poetry/poetry · error · EnvCommandError

Command {e.cmd} errored with the following return code {e.re

Error message

Command {e.cmd} errored with the following return code {e.returncode}

What it means

Raised as EnvCommandError inside base_env._run when a subprocess invocation (subprocess.check_call / check_output) launched within the managed virtualenv exits with a non-zero return code (subprocess.CalledProcessError). It wraps the failing command, its return code, and any captured stdout/stderr so the caller can see why the in-env command failed. It is the generic failure mode for every shell command Poetry runs inside an environment (pip installs, python -c probes, etc.).

Source

Thrown at src/poetry/utils/env/base_env.py:461

    def _run(self, cmd: list[str], **kwargs: Any) -> str:
        """
        Run a command inside the Python environment.
        """
        call = kwargs.pop("call", False)
        env = kwargs.pop("env", dict(os.environ))
        stderr = kwargs.pop("stderr", subprocess.STDOUT)

        try:
            if call:
                assert stderr != subprocess.PIPE
                subprocess.check_call(cmd, stderr=stderr, env=env, **kwargs)
                output = ""
            else:
                output = subprocess.check_output(
                    cmd, stderr=stderr, env=env, text=True, encoding="locale", **kwargs
                )
        except CalledProcessError as e:
            raise EnvCommandError(e)

        return output

    def execute(self, bin: str, *args: str, **kwargs: Any) -> int:
        command = self.get_command_from_bin(bin) + list(args)
        env = kwargs.pop("env", dict(os.environ))

        if not self._is_windows:
            return os.execvpe(command[0], command, env=env)

        kwargs["shell"] = True
        exe = subprocess.Popen(command, env=env, **kwargs)
        exe.communicate()
        return exe.returncode

    @abstractmethod
    def is_venv(self) -> bool: ...

View on GitHub (pinned to 92b74dcfe3)

Solutions

Read the appended 'Output:' / 'Error output:' section of the exception message - it carries the real underlying error from the subprocess.
Reproduce the failing command manually inside the venv (source the venv, run the exact cmd from e.cmd) to iterate faster.
Fix the root cause surfaced by the output (install build deps, fix network/proxy, correct package version) and re-run.
If the venv is corrupted, recreate it: 'poetry env remove <env>' then 'poetry install'.

Example fix

// before
env.run_pip("install", "some-broken-pkg==9.9.9")  # EnvCommandError

// after - inspect output, pin a buildable version
env.run_pip("install", "some-broken-pkg==1.2.3")

Defensive patterns

Strategy: try-catch

Validate before calling

import shutil, subprocess

def env_can_run(env, cmd: list[str]) -> bool:
    exe = cmd[0]
    return shutil.which(exe, path=env.path.as_posix()) is not None

# before calling env._run / run_pip:
assert env_can_run(env, ["pip"]), "pip missing in env"

Type guard

from subprocess import CalledProcessError

def is_env_command_error(e: Exception) -> bool:
    # EnvCommandError wraps a CalledProcessError on attribute .e
    return isinstance(e, Exception) and getattr(e, "e", None) is not None and isinstance(getattr(e, "e"), CalledProcessError)

Try / catch

from poetry.utils.env.exceptions import EnvCommandError, EnvError

try:
    env.run_pip("install", pkg)
except EnvCommandError as e:
    # e.e is the original CalledProcessError; e.e.output / e.e.stderr hold detail
    log.error("pip failed (rc=%s): %s", e.e.returncode, (e.e.stderr or b"").decode())
    raise
except EnvError:
    raise

Prevention

Always inspect e.e.output and e.e.stderr - the real cause is the wrapped subprocess output.
Pin reproducible dependency versions so pip resolution does not fail unpredictably.
Run long pip installs with a timeout and a local wheelhouse/cache to avoid transient network failures.
Recreate the venv if multiple unrelated commands start failing - it is likely corrupted.

When it happens

Trigger: Calling Env._run (directly or via methods that delegate to it, e.g. run_pip / run_python_script) with a command whose executable is missing inside the venv, whose arguments are invalid, or which itself exits non-zero (a pip install resolving a broken wheel, a build script that fails, a python -c that raises). Any path in base_env.py:443-461 that hits the CalledProcessError branch.

Common situations: A dependency fails to build its wheel under the current platform/Python; the venv's python or pip binary is corrupted/removed; network or index misconfiguration causes pip to abort; a post-install hook script errors. Also seen after manually deleting packages out from under the venv.

Related errors

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/4178932b9e2d7781.json. Report an issue: GitHub.