Gestionar y confugurar un entorno virtual¶

Cuando instalamos Python3, se crea un único entorno global compartido por todos los proyectos y todo el código de Python. Aunque es posible instalar Django y otros paquetes en el entorno global, esto limita la posibilidad de gestionar múltiples versiones de cada paquete.

Cuidado al trabajar en el entorno global

Los paquetes instalados globalmente pueden generar conflictos entre versiones, especialmente al trabajar con varios proyectos que requieren diferentes versiones de una misma biblioteca.

Como resultado, los desarrolladores experimentados suelen configurar y ejecutar las aplicaciones Python dentro de entornos virtuales de Python independientes.

¿Qué es un Entornos Virtual de Python?¶

Un entorno virtual en Python es una instancia aislada que se crea a partir de una copia de nuestro Python global. Su principal ventaja es que permite trabajar de forma ordenada en un proyecto específico, utilizando únicamente los módulos y librerías necesarios para ese caso, sin afectar a otros proyectos ni a la instalación global del sistema.

A continuación, se muestra un ejemplo de cómo luce un entorno virtual, lo que nos ayudará a comprender mejor su finalidad.

graph LR
    subgraph EG["Entorno global"]
        B(<img width='19' height='100' src="../../assets/images/base.webp" class="python-icon" />Python 3.9)
    end

    B --> T["Crear entornos virtuales independientes"]

    T --> C(<img width='19' height='100' src="../../assets/images/venv1.webp" />Entorno 1)
    T --> D(<img width='19' height='100' src="../../assets/images/venv2.webp" />Entorno 2)
    T --> E(<img width='19' height='100' src="../../assets/images/venv3.webp" />Entorno 3)

    subgraph CI["Entornos aislados con dependencias específicas"]
        C --> CD["Django 2.0"]
        D --> DD["Django 3.2"]
        E --> ED["Django 5.1"]
    end

Gestionar un Entorno Virtual¶

Existen varias herramientas para crear y gestionar entornos virtuales en Python. No hay un número único, pero estas son las principales que conviene conocer.

Herramientas más utilizadas¶

Herramienta	Descripción	Comando habitual
`venv`	Módulo estándar de Python; en Linux puede requerir instalación adicional.	`python -m venv .venv`
`virtualenv`	Alternativa a `venv`, con compatibilidad adicional.	`virtualenv .venv`
`Pipenv`	Combina entornos virtuales y gestión de dependencias.	`pipenv install`
`Poetry`	Gestiona dependencias, entornos y empaquetado de proyectos.	`poetry install`
`uv`	Herramienta rápida para Python; gestiona versiones, entornos y dependencias.	`uv venv`

Info

Ten presente que no todas estas herramientas son equivalentes: algunas crean entornos virtuales y otras también administran dependencias, versiones de Python y empaquetado.

Administrar entornos con `venv`¶

El paquete venv ya forma parte de la biblioteca estándar de Python desde la versión 3.3. Viene habitualmente incluido en la instalación estándar de Python en Windows, mientras que en algunas distribuciones de Linux puede requerir la instalación de un paquete por separado.

Para comprobarlo, ejecuta el siguiente comando:

Windows Linux / macOS Output

python -m venv --help

python3 -m venv --help

python -m venv --help
usage: python -m venv [-h] [--system-site-packages] [--symlinks |
                    --copies] [--clear] [--upgrade]
                    [--without-pip] [--prompt PROMPT]
                    [--upgrade-deps] [--without-scm-ignore-files]
                    ENV_DIR [ENV_DIR ...]

Creates virtual Python environments in one or more target
directories.

positional arguments:
ENV_DIR               A directory to create the environment in.

options:
-h, --help            show this help message and exit
--system-site-packages
                        Give the virtual environment access to the
                        system site-packages dir.
--symlinks            Try to use symlinks rather than copies, when
                        symlinks are not the default for the
                        platform.
--copies              Try to use copies rather than symlinks, even
                        when symlinks are the default for the
                        platform.
--clear               Delete the contents of the environment
                        directory if it already exists, before
                        environment creation.
--upgrade             Upgrade the environment directory to use
                        this version of Python, assuming Python has
                        been upgraded in-place.
--without-pip         Skips installing or upgrading pip in the
                        virtual environment (pip is bootstrapped by
                        default)
--prompt PROMPT       Provides an alternative prompt prefix for
                        this environment.
--upgrade-deps        Upgrade core dependencies (pip) to the
                        latest version in PyPI
--without-scm-ignore-files
                        Skips adding SCM ignore files to the
                        environment directory (Git is supported by
                        default).

Once an environment has been created, you may wish to activate it,
e.g. by sourcing an activate script in its bin directory.

En caso de no tener instalado venv, puedes usar los siguientes comandos:

Debian / Ubuntu Fedora

sudo apt update
sudo apt install python3-venv

sudo dnf install python3

Para gestionar un entorno virtual usando el paquete venv, ubicate en la carpeta donde quieres configurarlo y sigue los pasos según tu plataforma:

Administrar entornos con venv

Windows Linux / macOS

1. Crear Entorno Virtual

python -m venv .venv

2. Activar el Entorno Virtual

.venv\Scripts\activate.bat

3. Desactivar el Entorno Virtual

(.venv) deactivate

4. Limpiar el Entorno Virtual (recrearlo desde 0)

python -m venv --clear .venv

1. Crear Entorno Virtual

Terminal

python3 -m venv .venv

2. Activar el Entorno Virtual

Terminal

source .venv/bin/activate

3. Desactivar el Entorno Virtual

Terminal

(.venv) deactivate

4. Limpiar el Entorno Virtual (recrearlo desde 0)

Terminal

python3 -m venv --clear .venv

Nombre del entorno

Se recomienda utilizar venv o .venv como nombre del entorno virtual. La opción .venv es habitual porque se considera una carpeta oculta en sistemas Unix y ayuda a mantenerla separada del código del proyecto.

Administrar entornos con `virtualenv`¶

virtualenv es una herramienta alternativa a venv que permite crear y gestionar entornos virtuales aislados de Python. A diferencia de venv, que viene incluido en Python desde la versión 3.3, virtualenv se instala por separado y ofrece la creación más rápida de entornos.

Para instalarlo, ejecuta el siguiente comando:

PyPi macOS Debian / Ubuntu Fedora

# Windows
pip install virtualenv
# Linux
pip3 install virtualenv

brew install virtualenv

sudo apt update
sudo apt install python3-virtualenv

sudo dnf install python3-virtualenv

Administrar entornos con virtualenv

Windows Linux / macOS

1. Crear Entorno Virtual

virtualenv .venv

2. Activar el Entorno Virtual

.venv\Scripts\activate.bat

3. Desactivar el Entorno Virtual

deactivate

4. Limpiar el Entorno Virtual (recrearlo desde cero)

virtualenv --clear .venv

La opción --clear elimina el contenido existente del directorio del entorno antes de reconstruirlo.

5. Eliminar el Entorno Virtual

(.venv) deactivate
rmdir /s /q .venv

1. Crear Entorno Virtual

Terminal

virtualenv .venv

2. Activar el Entorno Virtual

Terminal

source .venv/bin/activate

3. Desactivar el Entorno Virtual

Terminal

deactivate

4. Limpiar el Entorno Virtual (recrearlo desde cero)

Terminal

virtualenv --clear .venv

La opción --clear elimina el contenido existente del directorio del entorno antes de reconstruirlo.

5. Eliminar el Entorno Virtual

Terminal

rm -rf .venv

Administrar entornos con `Pipenv`¶

Pipenv es una gran herramienta para gestionar entornos virtuales y dependencias de Python, destacando por integrar ambas tareas de forma flexible y sencilla.

Administración de entornos simplificado

Pipenv automáticamente crea y maneja un entorno virtual para tus proyectos, también como agregar/remover paquetes desde un archivo Pipfile.lock, que es usado para producir un determinado build.

Versiones requeridas para instalar Pipenv

Para la mayoría de los casos, se recomienda instalar Pipenv usando pip pero igual se puede instalar de otras manera según el Sistema Operativo:

PyPi macOS Debian / Ubuntu Fedora

# Windows
pip install --user pipenv
# Linux
pip3 install --user pipenv

Información

Al instalar Pipenv con la opción --user, es posible que deba agregar el directorio de los ejecutables al PATH para poder utilizar el comando pipenv desde la terminal.

En Linux y macOS, se puede consultar la ruta de instalación con:

Terminal

python3 -m site --user-base
# Output: /Users/mcherrera/Library/Python/3.14

Normalmente, los ejecutables se encuentran en el directorio bin dentro de esa ruta. Para agregarlo al PATH en Bash o Zsh, ejecute:

Terminal

echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc # o .zshrc si usas zsh

Finalmente, comprobamos que Pipenv esté disponible:

Terminal

pipenv --version
# Output: pipenv, version 2025.0.4

brew install pipenv

Advertencia

No se recomienda la instalación mediante Homebrew, ya que funciona mejor instalar pipenv usando pip en macOS.

sudo apt update
sudo apt install pipenv

sudo dnf install pipenv

Administrar entornos con Pipenv

Windows Linux / macOS

1. Crear un nuevo Entorno Virtual

pipenv install

Información

Si no existe un archivo Pipfile en el directorio del proyecto, Pipenv lo crea. Si ya existe, crea el entorno virtual e instala las dependencias definidas en el archivo, utilizando el archivo Pipfile.lock si está disponible.

2. Activar el Entorno Virtual

pipenv shell

3. Desactivar el Entorno Virtual

(.venv) exit

4. Limpiar la caché de dependencias

Terminal

pipenv --clear

5. Eliminar el Entorno Virtual asociado al proyecto

(.venv) exit
pipenv --rm

1. Crear un nuevo Entorno Virtual

Terminal

pipenv install

2. Activar el Entorno Virtual

Terminal

pipenv shell

3. Desactivar el Entorno Virtual

Terminal

(.venv) exit

4. Limpiar la caché de dependencias

Terminal

pipenv --clear

5. Eliminar el Entorno Virtual asociado al proyecto

Terminal

(.venv) exit
pipenv --rm

Administrar dependencias con Pipenv

1. Instalar un paquete (se registrará en el archivo Pipfile y Pipfile.lock)

Terminal

pipenv install requests

2. Eliminar un paquete o eliminar todos los paquetes

Terminal

pipenv uninstall requests
pipenv uninstall --all

Administrar entornos con `Poetry`¶

Poetry es una herramienta de Python que gestiona dependencias, entornos virtuales y empaqueta proyectos.

Información

Su diferencia principal con Pipenv es que Poetry permite construir y publicar librerías directamente en PyPI, mientras que Pipenv solo sirve para administrar dependencias de aplicaciones locales.

Poetry proporciona un instalador oficial que instala la herramienta en un entorno virtual independiente y administra su propio entorno.

En Linux, macOS y Windows mediante WSL, ejecuta el siguiente comando:

Terminal

curl -sSL https://install.python-poetry.org | python3 -

Info

Si el comando poetry no se reconoce, se debe agregar el directorio de instalación al PATH.

En Linux y macOS, normalmente puedes utilizar:

Terminal

export PATH="$HOME/.local/bin:$PATH"

Para conservar el cambio, añade esa línea al archivo ~/.bashrc o ~/.zshrc, según la terminal que utilices:

Terminal

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Verificar la instalación:

Terminal

poetry --version
# Output: Poetry (version 2.5.1)

Documentación oficial: Instalación de Poetry.

Administrar entornos con Poetry

Windows Linux / macOS

1. Inicializar el proyecto

poetry init --no-interaction

Genera el archivo pyproject.toml, donde se define la configuración del proyecto y sus dependencias. Si ya existe este archivo, puedes omitir este paso.

Info

Agrega package-mode = false a la sección [tool.poetry] del archivo pyproject.toml para indicarle a Poetry que no trate tu proyecto como un paquete Python que debe instalarse, sino que lo utilice únicamente para gestionar sus dependencias. Por ejemplo:

pyproject.toml
[project]
name = "tuto-django"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
requires-python = ">=3.12"
dependencies = [
    "django (>=6.1.2,<7.0.0)"
]

[tool.poetry]
package-mode = false 

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

2. Crear el Entorno Virtual

poetry env use python3.12

Selecciona el intérprete de Python que utilizará Poetry. Si el entorno virtual no existe, Poetry lo creará cuando sea necesario, por ejemplo, al ejecutar poetry install.

3. Activar el Entorno Virtual

poetry env activate

Poetry mostrará un comando, copia y ejecuta el comando que te devuelva Poetry para activar el entorno virtual.

4. Agregar e instalar un paquete (se agrega al pyproject.toml)

poetry add django

Poetry instala Django en el entorno virtual del proyecto, independientemente de que esté activado en tu terminal.

5. Eliminar el Entorno Virtual

(.venv) deactivate
poetry env remove python3.12

Esto elimina el entorno virtual asociado a Python 3.12, pero no elimina las dependencias declaradas en pyproject.toml ni el archivo poetry.lock.

1. Inicializar el proyecto

Terminal

poetry init

Genera el archivo pyproject.toml, donde se define la configuración del proyecto y sus dependencias. Si ya existe este archivo, puedes omitir este paso.

Info

Agrega package-mode = false a la sección [tool.poetry] del archivo pyproject.toml para indicarle a Poetry que no trate tu proyecto como un paquete Python que debe instalarse, sino que lo utilice únicamente para gestionar sus dependencias. Por ejemplo:

pyproject.toml
[project]
name = "tuto-django"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
requires-python = ">=3.12"
dependencies = [
    "django (>=6.1.2,<7.0.0)"
]

[tool.poetry]
package-mode = false 

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

2. Crear el Entorno Virtual

Terminal

poetry env use python3.12

3. Activar el Entorno Virtual

Terminal

eval "$(poetry env activate)"

4. Agregar e instalar un paquete (se agrega al pyproject.toml)

poetry add django

Poetry instala Django en el entorno virtual del proyecto, independientemente de que esté activado en tu terminal.

5. Eliminar el Entorno Virtual

Terminal

poetry env remove python3.12

Esto elimina el entorno virtual asociado a Python 3.12, pero no elimina las dependencias declaradas en pyproject.toml ni el archivo poetry.lock.

Administrar entornos con `uv`¶

uv es un gestor de paquetes, proyectos y entornos de Python con alto rendimiento desarrollado en Rust.

Está diseñado como una herramienta "todo en uno" que busca reemplazar varias herramientas tradicionales del ecosistema Python:

pip ( instalador de paquetes )
venv / virtualenv ( creadores de entornos virtuales )
pip-tools ( compilación y bloqueo de dependencias )
pipx ( ejecución e instalación de herramientas globales )
pyenv ( gestor de versiones de Python )

uv proporciona un instalador oficial que permite instalar la herramienta directamente en el sistema sin necesidad de instalarla mediante pip.

Linux / macOS Windows (PowerShell)

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -c "irm https://astral.sh/uv/install.ps1 | more"

Administrar entornos con uv

Windows Linux / macOS

1. Crear Entorno Virtual

uv venv .venv

2. Activar el Entorno Virtual

.venv\Scripts\activate.bat

3. Desactivar el Entorno Virtual

deactivate

4. Limpiar el Entorno Virtual (recrearlo desde cero)

uv venv --clear .venv

La opción --clear elimina el contenido existente del directorio del entorno antes de reconstruirlo.

5. Eliminar el Entorno Virtual

deactivate
rmdir /s /q .venv

1. Crear Entorno Virtual

Terminal

uv venv .venv

2. Activar el Entorno Virtual

Terminal

source .venv/bin/activate

3. Desactivar el Entorno Virtual

Terminal

deactivate

4. Limpiar el Entorno Virtual (recrearlo desde cero)

Terminal

uv venv --clear .venv

La opción --clear elimina el contenido existente del directorio del entorno antes de reconstruirlo.

5. Eliminar el Entorno Virtual

Terminal

deactivate
rm -rf .venv

Buenas prácticas¶

Utilizar .venv como nombre convencional del entorno.
Agregar .venv/ al archivo .gitignore.
Mantener las dependencias del proyecto en requirements.txt.
Utilizar un entorno independiente para cada proyecto.

¿Cuál te recomiendo?¶

1. venv — para aprender y proyectos sencillos

Ya viene con Python. Es una excelente opción para Django y proyectos académicos.

Terminal

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. uv — para desarrollo moderno

Es rápido y permite gestionar Python, entornos virtuales y dependencias desde una sola herramienta.

Terminal

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

Mi recomendación para tus proyectos Django: continúa con venv si quieres mantener una configuración sencilla. Si buscas una herramienta más completa y rápida, vale la pena aprender uv.

Gestionar y confugurar un entorno virtual¶

¿Qué es un Entornos Virtual de Python?¶

Gestionar un Entorno Virtual¶

Herramientas más utilizadas¶

Administrar entornos con venv¶

Administrar entornos con virtualenv¶

Administrar entornos con Pipenv¶

Administrar entornos con Poetry¶

Administrar entornos con uv¶

Buenas prácticas¶

¿Cuál te recomiendo?¶

Administrar entornos con `venv`¶

Administrar entornos con `virtualenv`¶

Administrar entornos con `Pipenv`¶

Administrar entornos con `Poetry`¶

Administrar entornos con `uv`¶