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 in EnvManager.remove when subprocess.check_output([python, '-c', GET_ENV_PATH_ONELINER]) fails with CalledProcessError. This happens for the code path at env_manager.py:283-293 where the argument is an existing file that Poetry assumed was a python executable, but invoking it to discover its env directory errored.

Source

Thrown at src/poetry/utils/env/env_manager.py:293

        This is done to prevent action on other project's envs.
        """
        return env.startswith(base_env_name)

    def remove(self, python: str) -> Env:
        python_path = Path(python)
        if python_path.is_file():
            # Validate env name if provided env is a full path to python
            try:
                env_dir = subprocess.check_output(
                    [python, "-c", GET_ENV_PATH_ONELINER], text=True, encoding="locale"
                ).strip("\n")
                env_name = Path(env_dir).name
                if not self.check_env_is_for_current_project(
                    env_name, self.base_env_name
                ):
                    raise IncorrectEnvError(env_name)
            except CalledProcessError as e:
                raise EnvCommandError(e)

        if self.check_env_is_for_current_project(python, self.base_env_name):
            venvs = self.list()
            for venv in venvs:
                if venv.path.name == python:
                    # Exact virtualenv name
                    if self.envs_file.exists():
                        venv_minor = ".".join(str(v) for v in venv.version_info[:2])
                        self.envs_file.remove_section(self.base_env_name, venv_minor)

                    self.remove_venv(venv.path)

                    return venv

            raise ValueError(
                f'<warning>Environment "{python}" does not exist.</warning>'
            )
        else:

View on GitHub (pinned to 92b74dcfe3)

Solutions

Run the failing probe yourself: '<path> -c "import sys; print(sys.prefix)"' and read the real error.
If the interpreter is broken, remove the leftover venv directory manually and reinstall the interpreter.
Point env remove at the env NAME (from 'poetry env list') instead of the raw python path.
Ensure the file is executable (chmod +x) and its shared libraries resolve (ldd <path>).

Example fix

// before
manager.remove("/opt/broken-python/bin/python")  # EnvCommandError

// after - fix or remove the broken interpreter, then remove by name
manager.remove("myproject-py3.11")

Defensive patterns

Strategy: validation

Validate before calling

import subprocess
from pathlib import Path

def interpreter_is_runnable(path: str) -> bool:
    p = Path(path)
    if not p.is_file():
        return False
    try:
        subprocess.check_output([path, "-c", "import sys; print(sys.prefix)"], text=True)
        return True
    except (subprocess.CalledProcessError, OSError):
        return False

Type guard

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

def is_env_command_error(e: Exception) -> bool:
    return isinstance(e, EnvCommandError) or isinstance(e, EnvError)

Try / catch

from poetry.utils.env.exceptions import EnvCommandError

try:
    manager.remove(python_path)
except EnvCommandError as e:
    # probe failed - try removing by env name instead
    name = pick_env_name_from(manager.list())
    manager.remove(name)

Prevention

Verify the interpreter runs (path -c 'print(1)') before passing it to env remove.
Prefer removing by env name from 'poetry env list' over raw interpreter paths.
Check the binary is executable and its shared libs resolve (ldd / otool -L).
Remove orphaned venv directories directly if the interpreter is unrecoverable.

When it happens

Trigger: Calling 'poetry env remove <path>' where <path>.is_file() is True but the file is not a runnable python interpreter (not executable, wrong arch, missing shared libs, or it exits non-zero when probed for sys.prefix).

Common situations: Pointing env remove at a python binary whose dependencies are missing (libpython .so removed), a stale symlink to a deleted interpreter, a file that merely happens to be named 'python', or a binary for the wrong platform.

Related errors

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