tooolbox/blog/Python 가상환경 venv 생성 에러 해결
troubleshooting2025-04-15·7·120/348

Python 가상환경 venv 생성 에러 해결

Step-by-step guide to fixing common Python venv creation errors on Windows, Linux, and macOS — from missing ensurepip to permission denied.

Python 가상환경 venv 생성 에러 해결

Introduction

Setting up a Python virtual environment should be a one-liner. Yet anyone who has worked across multiple machines or operating systems knows that python -m venv can fail in surprisingly varied ways. I have hit this issue on fresh Ubuntu servers, corporate Windows laptops, and even on my MacBook Pro after a Homebrew update.

After moving to Lisbon and setting up a new development environment for a freelance project, I spent a full hour debugging why venv would not create on my new machine. The root cause turned out to be a missing ensurepip module — something I had never thought about before.

Environment

The errors discussed here span multiple platforms and Python versions:

# Windows
Python 3.12.3 (tags/v3.12.3:82c7b5b)
Windows 11 Pro 23H2

# Linux (Ubuntu 24.04)
Python 3.12.3 (compiled from source or deadsnakes PPA)

# macOS
Python 3.11.8 (Homebrew)
macOS Sonoma 14.4

Problem

Here are the most common venv creation errors and what they look like.

Error 1: ensurepip is not available

$ python -m venv myenv
Error: Command '['/usr/bin/python3', '-m', 'ensurepip', '--upgrade', '--default-pip']' returned non-zero exit status 1.

This happens when your Python installation was built without the ensurepip module. It is common on Debian/Ubuntu-based systems where Python is installed from the system package manager.

Error 2: Permission denied

$ python -m venv myenv
Error: [Errno 13] Permission denied: '/usr/local/lib/python3.12/myenv'

This occurs when you try to create a venv inside a system directory without proper permissions.

Error 3: The PATH does not include pip

$ python -m venv myenv
Error: subprocess-exited-with-error

Error 4: Python not found as python

$ python -m venv myenv
'python' is not recognized as an internal or external command

Windows users who only have python3 or have not added Python to their PATH encounter this.

Analysis

Each error has a distinct root cause.

For ensurepip missing: Debian and Ubuntu strip ensurepip from the default Python package to save space. The fix is to install the python3-venv package.

For permission errors: You are either writing to a system directory or your user does not have write access to the target location.

For PATH issues: On Windows, Python's installer may not add Python to the system PATH. On Linux, python may not be symlinked to python3.

For Homebrew Python: Homebrew-managed Python sometimes has broken pip or ensurepip after a major version upgrade.

Solution

Fix 1: Install python3-venv on Debian/Ubuntu

# For system Python 3.12
sudo apt update
sudo apt install python3.12-venv

# Now venv works
python3 -m venv myenv

Fix 2: Use a user-space directory

# Instead of writing to a system directory
mkdir -p ~/projects/myproject
cd ~/projects/myproject
python3 -m venv .venv

Fix 3: Add Python to PATH on Windows

# In PowerShell, check if Python is in PATH
Get-Command python -ErrorAction SilentlyContinue

# If not found, find where Python is installed
Get-ChildItem "C:\Users\$env:USERNAME\AppData\Local\Programs\Python" -Recurse -Filter "python.exe"

# Add to PATH for the current session
$env:PATH += ";C:\Users\$env:USERNAME\AppData\Local\Programs\Python\Python312"

# Or add permanently via System Properties > Environment Variables

Fix 4: Use python3 explicitly

# This works even when 'python' is not defined
python3 -m venv .venv
source .venv/bin/activate

Fix 5: Install pip manually when ensurepip is broken

# Download get-pip.py
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py

# Create venv without pip first
python3 -m venv --without-pip myenv

# Activate and install pip
source myenv/bin/activate
python get-pip.py

Fix 6: For Homebrew Python on macOS

# Reinstall Python
brew reinstall python@3.12

# Or use the system Python
/usr/bin/python3 -m venv myenv

Lessons Learned

  • Always use python3 and pip3 explicitly instead of relying on python being defined.
  • Create venvs in user space, never inside system directories or the Python installation folder itself.
  • Install python3-venv on Debian/Ubuntu before your first venv creation attempt.
  • Keep a get-pip.py backup locally — it is a lifesaver when pip is broken inside a venv.
  • On Windows, verify PATH after Python installation and restart your terminal.

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.