Entornos virtuales con venv y pip

Dos proyectos en una misma computadora pueden necesitar dos versiones del mismo paquete, uno escrito para la versión 1 de una biblioteca y otro para la versión 2. Con un único Python, un solo pip install sirve a los dos, así que una actualización para un proyecto puede romper el otro, y el Python que vino con tu sistema operativo también puede ejecutar herramientas del propio sistema. Un entorno virtual da a cada proyecto una carpeta de paquetes propia.

A continuación creas un entorno y miras dentro, ves qué cambia al activarlo, instalas un paquete en él sin descargar nada, ves por qué muchos Python del sistema rechazan un pip install sin más, y reconstruyes un entorno en lugar de moverlo. Todas las órdenes se ejecutaron con el Python 3.14.8 de este curso, y la página muestra exactamente lo que imprimieron.

Un entorno virtual es una carpeta con sus propios paquetes

Un entorno virtual es una carpeta, por convención llamada .venv y guardada en la propia carpeta del proyecto. Dentro importan tres cosas:

• pyvenv.cfg, un pequeño archivo de texto que nombra el Python a partir del cual se creó el entorno, su Python base;
• bin/python (Scripts\python.exe en Windows), la propia orden python del entorno;
• lib/python3.14/site-packages (Lib\site-packages en Windows), adonde van los paquetes que instalas para este proyecto.

Crea uno con python3 -m venv .venv en la carpeta del proyecto, o py -m venv .venv en Windows. -m venv ejecuta el módulo venv del Python que escribiste, así que el entorno se construye sobre ese Python y mantiene su versión. La orden no imprime nada cuando funciona. En Debian necesita antes un paquete más: Debian distribuye venv en un paquete propio, python3-venv, y la documentación de Ubuntu incluye venv entre lo que añade su paquete python3-full. Este programa crea un entorno y mira dentro:

import sys
from pathlib import Path

from session import run

# The environment's programs are in .venv/bin (.venv\Scripts on Windows).
run("python3 -m venv .venv", sys.executable, "-m", "venv", ".venv")
print("In .venv:", sorted(p.name for p in Path(".venv").iterdir()))
print("pyvenv.cfg says:")
print(Path(".venv/pyvenv.cfg").read_text(), end="")
packages = Path(".venv/lib/python3.14/site-packages")
print("site-packages holds:", sorted(p.name for p in packages.iterdir()))
print(".gitignore holds:", Path(".venv/.gitignore").read_text().splitlines()[-1])

check = "import sys; print(sys.prefix != sys.base_prefix)"
run(f".venv/bin/python -c '{check}'", ".venv/bin/python", "-c", check)
run(f"python3 -c '{check}'", sys.executable, "-c", check)

$ python3 -m venv .venv
In .venv: ['.gitignore', 'bin', 'include', 'lib', 'pyvenv.cfg']
pyvenv.cfg says:
home = …/bin
include-system-site-packages = false
version = 3.14.8
executable = …/bin/python3.14
command = …/bin/python3 -m venv .venv
site-packages holds: ['pip', 'pip-26.2.1.dist-info']
.gitignore holds: *
$ .venv/bin/python -c 'import sys; print(sys.prefix != sys.base_prefix)'
True
$ python3 -c 'import sys; print(sys.prefix != sys.base_prefix)'
False

"""Runs a command as if you had typed it in a terminal, and prints what it printed."""
import os
import subprocess

# PIP_DISABLE_PIP_VERSION_CHECK: pip does not look online for a newer pip,
# so what these examples print does not depend on the network.
ENV = {**os.environ, "PIP_DISABLE_PIP_VERSION_CHECK": "1"}


def run(typed, *command):
    """Show the command as you would type it, run it, and print its output."""
    print("$", typed)
    result = subprocess.run(command, capture_output=True, text=True, env=ENV)
    print(result.stdout + result.stderr, end="")
    return result

Hay cuatro cosas que ver en esa salida. La biblioteca estándar no se copió: site-packages solo contiene pip, el único paquete con el que empieza un entorno nuevo, en la versión que incluye este Python, 26.2.1. pyvenv.cfg nombra la carpeta del Python base en home (la página acorta esa carpeta a …), y include-system-site-packages = false deja fuera los paquetes propios del Python base. venv escribió un .gitignore que contiene *, así que Git ignora toda la carpeta, cosa que venv hace desde Python 3.13. Y sys.prefix != sys.base_prefix es True dentro del entorno y False fuera: la documentación de venv da esta comparación como la forma de que un programa lo sepa.

¿Cómo sabe .venv/bin/python que pertenece a un entorno? Recorre un arranque y una importación:

Activarlo pone el python del entorno el primero en PATH

Typing .venv/bin/python every time is long. Activating the environment puts its bin folder (Scripts on Windows) first on your PATHPATH: The environment variable that lists the folders a shell searches, in order, for a command you type. A command whose folder is not on PATH answers "command not found" until the folder is added or the full path is typed., so that python, python3 and pip mean the environment’s until you type deactivate or close the terminal. Here is a bash shell before, during and after:

import subprocess
import sys

from session import run

run("python3 -m venv .venv", sys.executable, "-m", "venv", ".venv")

# The commands below run in one bash shell, one after another, as if typed.
commands = [
    "command -v python3",
    "source .venv/bin/activate",
    "command -v python3",
    'echo "$PS1"',
    "deactivate",
    "command -v python3",
]
script = "".join(f"echo '$ {line}'; {line}\n" for line in commands)
shell = subprocess.run(["bash", "-c", script], capture_output=True, text=True)
print(shell.stdout + shell.stderr, end="")

$ python3 -m venv .venv
$ command -v python3
…/bin/python3
$ source .venv/bin/activate
$ command -v python3
.venv/bin/python3
$ echo "$PS1"
(.venv) 
$ deactivate
$ command -v python3
…/bin/python3

Antes de activar, python3 era el Python base, el de este curso (acortado a …). Después de source .venv/bin/activate, el shell encontró primero .venv/bin/python3, y el indicador empezaba por (.venv), que es como puedes ver que hay un entorno activo. deactivate devolvió las dos cosas a su estado. La orden para activar depende de tu shell:

Si PowerShell se niega a ejecutar Activate.ps1, la documentación de venv da la orden que permite esos scripts para tu propio usuario: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser.

Activar es una comodidad, no un requisito. La ruta completa del intérprete del entorno ejecuta un programa en el entorno sin activar nada: .venv/bin/python main.py, o .venv\Scripts\python main.py en Windows. Así es como usan un entorno los editores y las tareas programadas.

pip instala en el entorno del python que lo ejecuta

python -m pip ejecuta el pip de ese python, así que instala en el entorno de ese python. El programa de abajo primero construye un pequeño archivo de paquete, un wheelwheel: Un paquete construido, un archivo zip con la extensión .whl, a menudo uno por plataforma. pip instala un wheel desempaquetando sus archivos, sin ejecutar el código del propio paquete. Más en “Buscar e instalar paquetes de terceros” (en inglés) hecho por make_wheel.py, para que la instalación no necesite descargar nada: --no-index --find-links wheels le dice a pip que busque solo en esa carpeta. Instalar desde PyPIPyPI: El Python Package Index, pypi.org, donde se publican la mayoría de los paquetes de Python de terceros. pip instala desde él salvo que se le diga que use otro índice o una carpeta de archivos. Más en “Buscar e instalar paquetes de terceros” (en inglés) funciona igual, con una descarga:

import sys

from make_wheel import make_wheel
from session import run

make_wheel("wheels")  # a package file to install from, so no download is needed
py = ".venv/bin/python"
run("python3 -m venv .venv", sys.executable, "-m", "venv", ".venv")
run(f"{py} -m pip --version", py, "-m", "pip", "--version")
run(
    f"{py} -m pip install --no-index --find-links wheels marksheet",
    py, "-m", "pip", "install", "--no-index", "--find-links", "wheels", "marksheet",
)
run(f"{py} -m pip list", py, "-m", "pip", "list")
where = "import marksheet; print(marksheet.__file__)"
run(f"{py} -c '{where}'", py, "-c", where)
run("python3 -c 'import marksheet'", sys.executable, "-c", "import marksheet")
run(f"{py} -m pip uninstall -y marksheet", py, "-m", "pip", "uninstall", "-y", "marksheet")

$ python3 -m venv .venv
$ .venv/bin/python -m pip --version
pip 26.2.1 from .venv/lib/python3.14/site-packages/pip (python 3.14)
$ .venv/bin/python -m pip install --no-index --find-links wheels marksheet
Looking in links: wheels
Processing ./wheels/marksheet-1.0.0-py3-none-any.whl
Installing collected packages: marksheet
Successfully installed marksheet-1.0.0
$ .venv/bin/python -m pip list
Package   Version
--------- -------
marksheet 1.0.0
pip       26.2.1
$ .venv/bin/python -c 'import marksheet; print(marksheet.__file__)'
.venv/lib/python3.14/site-packages/marksheet.py
$ python3 -c 'import marksheet'
Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import marksheet
ModuleNotFoundError: No module named 'marksheet'
$ .venv/bin/python -m pip uninstall -y marksheet
Found existing installation: marksheet 1.0.0
Uninstalling marksheet-1.0.0:
  Successfully uninstalled marksheet-1.0.0

"""Builds marksheet-1.0.0-py3-none-any.whl, a tiny package, so that no download is needed.

A wheel is a zip file: the package's code, and a NAME-VERSION.dist-info folder that
says what the package is and which commands it adds.
"""
import base64
import hashlib
import zipfile
from pathlib import Path

CODE = '''def grade(mark):
    return "pass" if mark >= 35 else "fail"


def main():
    print("72 is a", grade(72))
'''


def make_wheel(folder):
    info = "marksheet-1.0.0.dist-info"
    files = {
        "marksheet.py": CODE,
        f"{info}/METADATA": "Metadata-Version: 2.4\nName: marksheet\nVersion: 1.0.0\n",
        f"{info}/WHEEL": "Wheel-Version: 1.0\nGenerator: make_wheel.py\nRoot-Is-Purelib: true\nTag: py3-none-any\n",
        f"{info}/entry_points.txt": "[console_scripts]\nmarksheet = marksheet:main\n",
    }
    record = []
    for name, text in files.items():
        digest = base64.urlsafe_b64encode(hashlib.sha256(text.encode()).digest())
        record.append(f"{name},sha256={digest.rstrip(b'=').decode()},{len(text.encode())}")
    files[f"{info}/RECORD"] = "\n".join(record + [f"{info}/RECORD,,"]) + "\n"
    Path(folder).mkdir(exist_ok=True)
    wheel = Path(folder, "marksheet-1.0.0-py3-none-any.whl")
    with zipfile.ZipFile(wheel, "w") as archive:
        for name, text in files.items():
            archive.writestr(name, text)
    return wheel

pip --version nombra la carpeta desde la que se ejecuta su pip, el site-packages del entorno, y el paquete también acabó ahí, como .venv/lib/python3.14/site-packages/marksheet.py. Así que el python del entorno lo importa, y el python3 base se detiene con ModuleNotFoundError: ese aislamiento es para lo que sirve un entorno virtual. Con el entorno activo, un python -m pip sin más significa lo mismo:

Pon entre comillas un rango de versiones, como en la segunda fila: sin las comillas, el shell lee < y > como redirecciones. Como mostró la lección del REPL, python -m pip también asegura que se ejecuta el pip del intérprete correcto, mientras que un pip sin más puede pertenecer a otro Python de tu PATH.

Muchos Python del sistema rechazan pip install fuera de un entorno

Ejecuta python3 -m pip install requests con el Python de Debian 12 o posterior, o con el de Homebrew en un Mac, fuera de cualquier entorno, y pip se detiene con error: externally-managed-environment y This environment is externally managed. Ese Python pertenece al gestor de paquetes del sistema, que instala él mismo sus paquetes; un pip install podría sustituir un paquete que necesita una herramienta del sistema. La regla es un estándar de empaquetado, de la PEP 668. Recorre la comprobación que hace pip 26.2.1 antes de instalar:

Un programa puede hacer la misma comprobación que hace pip. El Python 3.14.8 de este curso lo instaló un gestor de versiones, mise, no el gestor de paquetes de un sistema, así que todas las respuestas son False: nada lo marca como gestionado.

import sys
import sysconfig
from pathlib import Path

in_venv = sys.prefix != sys.base_prefix
marker = Path(sysconfig.get_path("stdlib"), "EXTERNALLY-MANAGED")

print("Python", sys.version.split()[0])
print("Inside a virtual environment:", in_venv)
print("Marked as externally managed:", marker.exists())
print("A plain pip install would be refused:", marker.exists() and not in_venv)

Python 3.14.8
Inside a virtual environment: False
Marked as externally managed: False
A plain pip install would be refused: False

Ejecuta el mismo archivo con el python3 de Debian 12 o de Homebrew y la tercera línea dice True, igual que la cuarta, salvo que lo ejecutes desde un entorno virtual, donde pip siempre puede instalar. Cuando te encuentres con el error:

• Para todo lo que importa tu propio código, crea un entorno virtual, como en esta lección.
• Para una aplicación de línea de órdenes que quieres tener en todas partes, instálala con pipx, la herramienta de la lección siguiente, que da a cada aplicación un entorno propio.
• Para una biblioteca que empaqueta el propio sistema, instala el paquete del sistema con su gestor de paquetes, como sugiere el mensaje del Python de Debian (apt install python3-xyz).

Borra y reconstruye un entorno, nunca lo muevas

No hay nada tuyo en .venv, así que borrarlo es seguro: elimina la carpeta (rm -rf .venv en macOS y Linux, Remove-Item -Recurse .venv en PowerShell, o con tu gestor de archivos). Antes, anota las versiones exactas en un archivo de requisitosarchivo de requisitos: Un archivo de texto, normalmente requirements.txt, con un requisito por línea, que instala pip install -r. pip freeze escribe uno que enumera cada paquete instalado con su versión exacta. Más en “Buscar e instalar paquetes de terceros” (en inglés) con pip freeze, para que un entorno nuevo pueda volver a tener los mismos paquetes.

Lo que rompe las cosas es moverlo. Cada orden que instala pip, como marksheet abajo, es un pequeño script cuya primera línea, #!, contiene la ruta completa del python del entorno, así que después de moverlo esa ruta ya no existe. El programa muestra el ciclo completo, de congelar a reconstruir:

import os
import shutil
import subprocess
import sys
from pathlib import Path

from make_wheel import make_wheel
from session import run


def first_line(script):
    """Where the #! line of a script that pip installed points, and whether that python exists."""
    python = script.read_text().splitlines()[0].removeprefix("#!")
    print(f"  {script} starts with #! and the full path of {os.path.relpath(python)};",
          "it exists:", Path(python).exists())


make_wheel("wheels")
py = ".venv/bin/python"
find = ["--no-index", "--find-links", "wheels"]
run("python3 -m venv .venv", sys.executable, "-m", "venv", ".venv")
run(f"{py} -m pip install --no-index --find-links wheels marksheet", py, "-m", "pip", "install", *find, "marksheet")
frozen = run(f"{py} -m pip freeze", py, "-m", "pip", "freeze").stdout
Path("requirements.txt").write_text(frozen)  # what pip freeze > requirements.txt does
first_line(Path(".venv/bin/marksheet"))

print("$ mv .venv moved")
shutil.move(".venv", "moved")
first_line(Path("moved/bin/marksheet"))
print("$ moved/bin/marksheet")
try:
    subprocess.run(["moved/bin/marksheet"], check=True)
except FileNotFoundError as error:  # the python its #! line names is gone
    print("  it does not start:", error.strerror)

print("$ rm -rf moved")
shutil.rmtree("moved")
run("python3 -m venv .venv", sys.executable, "-m", "venv", ".venv")
run(f"{py} -m pip install --no-index --find-links wheels -r requirements.txt",
    py, "-m", "pip", "install", *find, "-r", "requirements.txt")
run(".venv/bin/marksheet", ".venv/bin/marksheet")

$ python3 -m venv .venv
$ .venv/bin/python -m pip install --no-index --find-links wheels marksheet
Looking in links: wheels
Processing ./wheels/marksheet-1.0.0-py3-none-any.whl
Installing collected packages: marksheet
Successfully installed marksheet-1.0.0
$ .venv/bin/python -m pip freeze
marksheet==1.0.0
  .venv/bin/marksheet starts with #! and the full path of .venv/bin/python; it exists: True
$ mv .venv moved
  moved/bin/marksheet starts with #! and the full path of .venv/bin/python; it exists: False
$ moved/bin/marksheet
  it does not start: No such file or directory
$ rm -rf moved
$ python3 -m venv .venv
$ .venv/bin/python -m pip install --no-index --find-links wheels -r requirements.txt
Looking in links: wheels
Processing ./wheels/marksheet-1.0.0-py3-none-any.whl (from -r requirements.txt (line 1))
Installing collected packages: marksheet
Successfully installed marksheet-1.0.0
$ .venv/bin/marksheet
72 is a pass

La orden movida seguía nombrando .venv/bin/python, que ya no existía, así que no arrancó (la página escribe esa ruta completa relativa a la carpeta del ejemplo). El entorno reconstruido a partir de requirements.txt vuelve a funcionar, con el mismo marksheet 1.0.0. La documentación de venv dice lo mismo: los entornos no se pueden mover ni copiar, así que se vuelven a crear en el nuevo lugar.

Practica: comprobar un entorno

Dos funciones cortas usan las ideas de esta lección: una dice si un programa se ejecuta en un entorno virtual, y la otra lee las versiones que anotó pip freeze. Los dos pasos vienen con código inicial, una primera pista y pruebas de ejemplo que puedes ejecutar aquí en la página, así que hazlos en el orden que quieras:

def in_virtualenv(sys_module):
    """Return True if the Python that sys_module describes runs in a virtual environment."""
    return None

import sys
from types import SimpleNamespace

from venvcheck import in_virtualenv


def test_inside_an_environment():
    """a prefix that differs from base_prefix means a virtual environment"""
    fake = SimpleNamespace(prefix="/home/asha/marks/.venv", base_prefix="/usr")
    assert in_virtualenv(fake) is True


def test_base_python():
    """the same prefix and base_prefix means the base Python itself"""
    fake = SimpleNamespace(prefix="/usr", base_prefix="/usr")
    assert in_virtualenv(fake) is False


def test_windows_paths():
    """works the same with Windows paths"""
    fake = SimpleNamespace(prefix="C:\\marks\\.venv", base_prefix="C:\\Python314")
    assert in_virtualenv(fake) is True


def test_this_python():
    """agrees with the sys module of the Python that runs the tests"""
    assert in_virtualenv(sys) == (sys.prefix != sys.base_prefix)

def pinned_versions(text):
    """Return {name: version} for every name==version line of pip freeze's output."""
    versions = {}
    return versions

from frozen import pinned_versions


def test_two_pins():
    """reads every name==version line"""
    text = "marksheet==1.0.0\ntablekit==2.3.1\n"
    assert pinned_versions(text) == {"marksheet": "1.0.0", "tablekit": "2.3.1"}


def test_blank_lines_and_comments():
    """skips blank lines and comments"""
    text = "# written by pip freeze\n\nmarksheet==1.0.0\n"
    assert pinned_versions(text) == {"marksheet": "1.0.0"}


def test_spaces_around_a_line():
    """ignores spaces around a line"""
    assert pinned_versions("  marksheet==1.0.0  \n") == {"marksheet": "1.0.0"}


def test_a_file_instead_of_a_version():
    """skips a line that records a file instead of a version"""
    text = "marksheet @ file:///home/asha/wheels/marksheet-1.0.0-py3-none-any.whl\ntablekit==2.3.1\n"
    assert pinned_versions(text) == {"tablekit": "2.3.1"}


def test_empty_text():
    """gives an empty dict for empty text"""
    assert pinned_versions("") == {}

Cuando pasen los dos pasos, prueba las preguntas de abajo. Eligen la idea de esta lección que menos dominas, y la explicación de una opción equivocada dice qué se le escapa:

Preguntas de entrevista

Calentamiento (júnior): ¿qué es un entorno virtual, y por qué usar uno para cada proyecto?

Un entorno virtual es una carpeta, normalmente .venv dentro del proyecto, con su propia orden python y su propia carpeta site-packages, creada por python3 -m venv .venv. Su pyvenv.cfg apunta al Python base, cuyo intérprete y biblioteca estándar usa, así que solo los paquetes son suyos. Un entorno por proyecto significa que cada proyecto tiene exactamente las versiones que necesita: uno puede usar la versión 1 de una biblioteca mientras otro usa la 2, una actualización en uno no puede romper el otro, y el propio Python del sistema queda intacto. El entorno se puede borrar y reconstruir a partir de requirements.txt en cualquier momento, y por eso nunca se sube al repositorio: se sube la lista de paquetes, no la carpeta.

Dos preguntas más difíciles parten de esta lección: un servidor que rechaza pip install, y una tarea programada que no encuentra un paquete que tu terminal sí encuentra. Piensa tu primer paso antes de abrir cada una:

Para recordar

• Un entorno virtual es una carpeta (.venv) con su propio python y su propio site-packages, construida sobre un Python base cuyo intérprete y biblioteca estándar comparte; créalo con python3 -m venv .venv, o py -m venv .venv en Windows.
• Activar pone la carpeta bin del entorno la primera en PATH; .venv/bin/python ejecuta un programa en el entorno sin activar nada.
• python -m pip instala en el entorno del python que lo ejecuta, y solo ahí, y por eso el Python base no puede importar el paquete.
• error: externally-managed-environment significa que el Python pertenece al sistema: usa un entorno virtual o pipx, nunca sudo pip ni --break-system-packages.
• Anota las versiones exactas con pip freeze > requirements.txt, y reconstruye un entorno a partir de ese archivo en lugar de moverlo o copiarlo, porque los scripts instalados contienen su ruta completa.
• sys.prefix != sys.base_prefix le dice a un programa que se ejecuta dentro de un entorno virtual.