{"id":"6fdfd724edc659d2","repo":"pypa/pip","slug":"venv-creation-error","errorCode":"venv-creation-error","errorMessage":"Cannot create a virtual environment","messagePattern":"Cannot create a virtual environment","errorType":"exception","errorClass":"VenvCreationError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/build_env/venv.py","lineNumber":51,"sourceCode":"    def __init__(self, installer: BuildEnvironmentInstaller) -> None:\n        # We defer this import because certain distributions of Python do not include\n        # a functional venv out of the box.\n        try:\n            import venv\n        except ImportError:\n            raise VenvImportError\n\n        self._env_path = TempDirectory(\n            kind=tempdir_kinds.BUILD_ENV, globally_managed=True\n        ).path\n        # Use symlinks to support relocatable Python installations on POSIX, including\n        # python-build-standalone. This matches upstream venv CLI's behaviour.\n        env = venv.EnvBuilder(symlinks=(os.name != \"nt\"))\n        try:\n            context = env.ensure_directories(self._env_path)\n            env.create(self._env_path)\n        except OSError as e:\n            raise VenvCreationError(str(e))\n\n        if sys.version_info >= (3, 12):\n            # The context object was only documented in Python 3.12\n            self.lib_dirs = [context.lib_path]\n            self._bin_path = context.bin_path\n        elif sys.version_info[:2] == (3, 11):\n            # On Python 3.11, we can use sysconfig.\n            self.lib_dirs = [_get_venv_path_from_sysconfig(\"purelib\", self._env_path)]\n            self._bin_path = _get_venv_path_from_sysconfig(\"scripts\", self._env_path)\n        else:\n            # Otherwise, we need to manually construct all the paths... sigh.\n            if sys.platform == \"win32\":\n                libpath = os.path.join(self._env_path, \"Lib\", \"site-packages\")\n            else:\n                python = \"pypy\" if sys.implementation.name == \"pypy\" else \"python\"\n                libpath = os.path.join(\n                    self._env_path,\n                    \"lib\",","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/build_env/venv.py#L33-L69","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\npip install --use-feature=venv-isolation mypkg\n# fails with OSError on venv creation\n\n# after\nexport TMPDIR=/var/tmp  # writable with space\npip install --use-feature=venv-isolation mypkg\n# or simply:\npip install mypkg","handlingStrategy":"validation","validationCode":"import os, shutil\n# Check temp dir is writable and has space\ntmp = os.environ.get('TMPDIR', '/tmp')\nif not os.access(tmp, os.W_OK):\n    raise RuntimeError(f'Temp dir {tmp} is not writable')\nusage = shutil.disk_usage(tmp)\nif usage.free < 500 * 1024 * 1024:\n    raise RuntimeError(f'Less than 500MB free in {tmp}')","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import VenvCreationError\ntry:\n    # install with venv-isolation\nexcept VenvCreationError as e:\n    # e.reference == 'venv-creation-error'\n    # retry without venv-isolation\n","preventionTips":["Ensure /tmp (or TMPDIR) has adequate free space (>1GB).","Verify write permissions on the temp directory.","Have a fallback without --use-feature=venv-isolation."],"tags":["venv","build-isolation","venv-isolation","filesystem","permissions","pep517"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}