Apuntes de Python

Apariencia

🐞 ModuleNotFoundError: No module named '_tkinter' con Python de Homebrew (macOS) ​

Apareció al intentar correr la primera app de customtkinter del ejercicio 01-formulario-registro.

🔍 Contexto ​

Cadena de 3 problemas de entorno, uno detrás de otro, todos por usar el Python instalado con Homebrew en macOS:

  1. pip install customtkinter → zsh: command not found: pip
  2. pip3 install customtkinter → error: externally-managed-environment
  3. Ya instalado dentro de un venv, al correr app.py → ModuleNotFoundError: No module named '_tkinter'

🧩 Por qué pasa cada uno ​

ErrorCausa
pip no existeEn Homebrew solo se instala el comando pip3, no el alias corto pip (ver nota en 01-Comandos)
externally-managed-environmentHomebrew protege el Python del sistema para que no le instales paquetes sueltos con pip — hay que usar un venv
No module named '_tkinter'tkinter es una librería de Python que en realidad envuelve una dependencia del sistema (Tcl/Tk) escrita en C. El Python de Homebrew no la trae compilada por defecto — hay que instalar el paquete de Homebrew aparte

✅ Solución (en orden) ​

bash
# 1. Crear un entorno virtual para el proyecto
python3 -m venv .venv
source .venv/bin/activate

# 2. Instalar las librerías del proyecto DENTRO del venv
pip install customtkinter

# 3. Instalar el soporte de Tcl/Tk para tu versión exacta de Python
brew install python-tk@3.14   # cambia el número por tu versión (python3 --version)

Después de eso, hay que decirle a VSCode que use el intérprete del venv: Cmd+Shift+P → "Python: Select Interpreter" → elegir .venv/bin/python.

✔️ Cómo confirmar que quedó bien ​

bash
python -c "import tkinter; print('tkinter OK')"

Si imprime tkinter OK, el problema está resuelto.

📌 Este paso de brew install python-tk@<versión> solo hace falta una vez por versión de Python en la máquina, no por proyecto — pero como cada venv nuevo puede usar una versión distinta de Python, vale la pena recordarlo si el error reaparece en otro curso.

🔗 Relacionado ​