What causes "Cannot create a virtual environment" in pypa/pip?

Check available disk space with `df -h` and free space if full.

pypa/pip · error · VenvCreationError

venv-creation-error

venv-creation-error

Error message

Cannot create a virtual environment

What it means

Raised by VenvBuildEnvironment.__init__() at venv.py:51 when an OSError occurs during venv creation (env.ensure_directories or env.create). The error is wrapped in VenvCreationError (reference: 'venv-creation-error') with the underlying OSError message as context. This happens during PEP 517 build isolation when venv-based isolation is used.

Source

Thrown at src/pip/_internal/build_env/venv.py:51

    def __init__(self, installer: BuildEnvironmentInstaller) -> None:
        # We defer this import because certain distributions of Python do not include
        # a functional venv out of the box.
        try:
            import venv
        except ImportError:
            raise VenvImportError

        self._env_path = TempDirectory(
            kind=tempdir_kinds.BUILD_ENV, globally_managed=True
        ).path
        # Use symlinks to support relocatable Python installations on POSIX, including
        # python-build-standalone. This matches upstream venv CLI's behaviour.
        env = venv.EnvBuilder(symlinks=(os.name != "nt"))
        try:
            context = env.ensure_directories(self._env_path)
            env.create(self._env_path)
        except OSError as e:
            raise VenvCreationError(str(e))

        if sys.version_info >= (3, 12):
            # The context object was only documented in Python 3.12
            self.lib_dirs = [context.lib_path]
            self._bin_path = context.bin_path
        elif sys.version_info[:2] == (3, 11):
            # On Python 3.11, we can use sysconfig.
            self.lib_dirs = [_get_venv_path_from_sysconfig("purelib", self._env_path)]
            self._bin_path = _get_venv_path_from_sysconfig("scripts", self._env_path)
        else:
            # Otherwise, we need to manually construct all the paths... sigh.
            if sys.platform == "win32":
                libpath = os.path.join(self._env_path, "Lib", "site-packages")
            else:
                python = "pypy" if sys.implementation.name == "pypy" else "python"
                libpath = os.path.join(
                    self._env_path,
                    "lib",

View on GitHub (pinned to d7d0d0a394)

Solutions

Check available disk space with `df -h` and free space if full.
Verify write permissions on the temp directory (set TMPDIR to a writable location).
Remove `--use-feature=venv-isolation` to use the default virtual-environment isolation.
On SELinux systems, ensure the policy allows venv creation in the temp directory.
If in Docker, ensure the container's filesystem is not read-only.

Example fix

# before
pip install --use-feature=venv-isolation mypkg
# fails with OSError on venv creation

# after
export TMPDIR=/var/tmp  # writable with space
pip install --use-feature=venv-isolation mypkg
# or simply:
pip install mypkg

Defensive patterns

Strategy: validation

Validate before calling

import os, shutil
# Check temp dir is writable and has space
tmp = os.environ.get('TMPDIR', '/tmp')
if not os.access(tmp, os.W_OK):
    raise RuntimeError(f'Temp dir {tmp} is not writable')
usage = shutil.disk_usage(tmp)
if usage.free < 500 * 1024 * 1024:
    raise RuntimeError(f'Less than 500MB free in {tmp}')

Try / catch

from pip._internal.exceptions import VenvCreationError
try:
    # install with venv-isolation
except VenvCreationError as e:
    # e.reference == 'venv-creation-error'
    # retry without venv-isolation

Prevention

Ensure /tmp (or TMPDIR) has adequate free space (>1GB).
Verify write permissions on the temp directory.
Have a fallback without --use-feature=venv-isolation.

When it happens

Trigger: Using `pip install --use-feature=venv-isolation <package>` (or a future default that uses venv isolation) and the venv.EnvBuilder.create() call raises an OSError. Common causes include insufficient disk space, permission denied on the temp directory, or a read-only filesystem.

Common situations: Running pip in a container or CI runner with a full /tmp or restricted /tmp permissions. Read-only root filesystem (e.g., some Docker images). SELinux or AppArmor blocking venv symlink creation. Disk quota exceeded.

Related errors

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