¡El NameError de Python no da miedo! Guía completa del error "variable no definida" para principiantes

Cuando estás empezando a aprender a programar, ver esos mensajes de error en letras rojas puede sentirse como si te dijeran "no puedes hacerlo", y es fácil desanimarse, ¿verdad? Para ser sincero, hasta hace solo unos meses, yo no tenía ningún conocimiento de programación y me pasaba los días mirando pantallas de error.

Uno de los primeros muros con los que se topan los principiantes es, sin duda, el error `NameError: name '...' is not defined`.

Pero no te preocupes. Este error no es nada difícil. De hecho, es solo la forma amable de Python de decirte: "Lo siento, no conozco el nombre '...' que me acabas de decir...".

En este artículo, como alguien que ha lanzado dos sitios web por su cuenta en un mes y medio con la ayuda de la IA, te explicaré qué es un `NameError` y cómo solucionarlo desde la misma "perspectiva de principiante" que tú, de forma exhaustiva y más clara que en ningún otro sitio. No usaré jerga técnica. A través de ejemplos concretos en los que yo mismo tropecé, te prometo que cuando termines de leer este artículo, serás capaz de resolver un `NameError` por ti mismo.

Y lo más importante, he preparado un montón de código que puedes simplemente copiar y pegar para experimentar el "¡funciona!". ¡Redescubramos juntos la alegría de programar a través de la satisfacción de resolver errores!

Para empezar, ¿qué es un NameError? - La señal de Python que dice "¡No conozco eso!"

Primero, veamos con un código simple cuándo ocurre un `NameError`. Este es un error con el que Python te dice: "No conozco ese nombre". El programa recuerda los nombres de las variables y funciones que escribes, pero si lo llamas con un nombre que no recuerda, se confunde y piensa "¿Espera, quién es ese?". Esa es la esencia de un `NameError`.

Por ejemplo, supongamos que ejecutas el siguiente código.

# Intentando mostrar un mensaje de saludo
print(message)
            

Al ejecutar esto, obtendrás este error el 100% de las veces.

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'message' is not defined
            

`NameError: name 'message' is not defined` se traduce literalmente como "Error de nombre: el nombre 'message' no está definido". En otras palabras, a Python se le dijo que mostrara algo llamado `message` con `print()`, pero como en ningún lado se le explicó qué es `message` (no está definido), lanzó un error y detuvo el proceso.

El mensaje de error (Traceback) es una pista crucial que te dice dónde está el problema. `File "<stdin>", line 1` significa "el error ocurrió en la línea 1". Usemos esta pista para investigar la causa.

[Por Causa] Los 3 casos más comunes de NameError y sus soluciones

La mayoría de los `NameError` que he encontrado han sido causados por una de las siguientes tres razones. Veámoslos uno por uno, con historias concretas de mis fracasos y código corregido listo para copiar y pegar.

Caso 1: Un simple error tipográfico (falta de ortografía)

Esta es la causa más común, y quizás la más difícil de detectar. Yo mismo pasé 30 minutos atascado por escribir "`mesage`" en lugar de "`message`". Python reconoce los nombres de variables y funciones como cosas completamente diferentes si un solo carácter es distinto.

❌ Ejemplo incorrecto (causa NameError)

Definimos una variable `greeting` e intentamos imprimirla, pero hemos cometido un error tipográfico (`greting`) dentro de la función `print()`.

# Guardar un saludo en la variable "greeting"
greeting = "¡Hola, mundo!"

# ¡Un error tipográfico al intentar imprimirlo!
print(greting) # ← ¡Falta una 'g'!
            

Resultado del error:

NameError: name 'greting' is not defined

✅ Ejemplo correcto (funciona bien)

Corrige el error tipográfico y llama a la función `print()` con el mismo nombre que la variable definida, `greeting`. Con solo hacer esto, el error desaparece como por arte de magia.

# Guardar un saludo en la variable "greeting"
greeting = "¡Hola, mundo!"

# Imprimir usando el nombre de variable correcto
print(greeting)
            

Resultado de la ejecución:

¡Hola, mundo!

[Consejo para solucionar problemas] Cuando te aparezca un `NameError`, primero compara cuidadosamente el nombre que se muestra en el mensaje de error (como `'greting'`) con el nombre de la variable que pretendías definir (`greeting`), carácter por carácter, para verificar si hay errores tipográficos.

Caso 2: Usar una variable antes de definirla

Un programa se ejecuta, por lo general, secuencialmente de arriba hacia abajo. Es como una receta de cocina. Aunque "echar sal" sea el primer paso en la receta, si antes no has completado el paso de "preparar el pollo", no sabrás a qué echarle sal, ¿verdad? Python funciona igual; obtendrás un `NameError` si intentas usar una variable antes de asignarle un valor (definirla).

❌ Ejemplo incorrecto (causa NameError)

Estamos intentando imprimir el nombre del usuario, `user_name`, pero la línea que de hecho le asigna un nombre a `user_name` viene después.

# Intentar imprimir la variable antes de saber qué contiene
print(user_name)

# Asignar un nombre a la variable después de intentar imprimirla
user_name = "López"
            

Resultado del error:

NameError: name 'user_name' is not defined

✅ Ejemplo correcto (funciona bien)

Corrige el orden de las operaciones. Primero, asigna (define) la cadena "López" a `user_name`, y luego llama a `print()` para mostrarla.

# Primero, asignar un nombre a la variable (definirla)
user_name = "López"

# Después de definirla, mostrar la variable
print(user_name)
            

Resultado de la ejecución:

López

[Consejo para solucionar problemas] Si obtienes un `NameError`, comprueba si la variable ha sido definida correctamente en una línea anterior a la línea donde ocurrió el error. Seguir el flujo del programa con el dedo de arriba hacia abajo también puede ser efectivo.

Caso 3: El muro del "ámbito" (scope) - usar una variable fuera de su alcance

Este es un tema un poco más avanzado, pero es una gran trampa en la que caen los principiantes. El "ámbito" (scope) se refiere, en pocas palabras, al "rango de validez de una variable". A menudo lo llamo "la habitación de la variable".

Una variable definida dentro de una función (una variable local) solo se puede usar dentro de la habitación de esa función. Si intentas usar esa variable desde fuera de la función, Python te devolverá un `NameError`, diciendo: "No hay ninguna variable con ese nombre en esta habitación (el ámbito global)".

❌ Ejemplo incorrecto (causa NameError)

Se define una variable `local_msg` dentro de la función `create_message`. Esta variable solo es válida dentro de la habitación de `create_message`. Sin embargo, estamos intentando llamarla desde fuera de la función (fuera de la habitación) con `print(local_msg)`, lo que causa un error.

def create_message():
    # Esta variable solo es válida dentro de la "habitación" de la función create_message()
    local_msg = "Este es un mensaje local"
    print("Visible desde dentro de la función:", local_msg)

# Ejecutar la función
create_message()

# Intentar usar la variable desde fuera de la "habitación" de la función
print(local_msg) # ← ¡Error aquí!
            

Resultado del error:

Visible desde dentro de la función: Este es un mensaje local
Traceback (most recent call last):
  File "<stdin>", line 9, in <module>
NameError: name 'local_msg' is not defined

El primer `print` tiene éxito, pero podemos ver que el error ocurre en la línea 9.

✅ Ejemplo correcto (funciona bien)

Si quieres usar un valor de dentro de la habitación de una función en el exterior, necesitas usar `return` para pasarlo como el "valor de retorno" de la función. Imagina que la función devuelve un valor y tú lo atrapas con una nueva variable.

def create_message():
    # Esta variable solo es válida dentro de la "habitación" de la función create_message()
    local_msg = "Este es un mensaje para pasar al exterior"
    # Usar return para pasar el "valor" de la variable fuera de la función
    return local_msg

# Ejecutar la función y recibir el valor de retorno en una variable llamada message_from_func
message_from_func = create_message()

# Mostrar la variable recibida
print(message_from_func)
            

Resultado de la ejecución:

Este es un mensaje para pasar al exterior

[Consejo para solucionar problemas] La forma estándar de usar un valor creado dentro de una función en el exterior es devolverlo con `return`. Aunque existe una forma de modificar una variable externa desde dentro de una función usando la palabra clave `global`, tiende a complicar los programas. Por lo tanto, se recomienda dominar primero el uso de `return`. Este tema también se explica en detalle en el sitio web oficial de Python como las reglas para variables locales y globales.

¡Depura con IA! Una técnica práctica para resolver NameErrors a la velocidad de la luz

Quieres pasar menos tiempo preocupándote por resolver errores y más tiempo en trabajo creativo, ¿verdad? En esos momentos, tu mejor compañero es una IA (como ChatGPT o Gemini).

Hoy en día, cada vez que me encuentro con un `NameError`, sigo siempre estos pasos para pedir ayuda a la IA:

1. Copia todo el mensaje de error: Selecciona y copia toda la información del error que se muestra en la terminal, desde `Traceback` hasta `NameError: ...`.
2. Pégalo y pregunta a la IA: Abre la ventana de chat de la IA, pregunta "Por favor, explica la causa de este error de Python de una manera que un principiante pueda entender" y pega el mensaje de error copiado.
3. Revisa tu código basándote en la respuesta de la IA: En la mayoría de los casos, la IA señalará la causa exacta, diciendo algo como: "La variable '...' no está definida. Es probable que sea un error tipográfico o que la estés llamando antes de definirla".

Justo el otro día, obtuve un `NameError` en un código que llamaba una clave de diccionario, y no pude encontrar la causa por mi cuenta. Pero cuando le pasé todo el código y el error a una IA, me dijo al instante: "Al llamar una clave de diccionario, necesitas encerrarla entre comillas como `'key_name'`, pero estás intentando llamarla como una variable sin comillas, lo que está causando el `NameError`".

Al utilizar la IA como un compañero de depuración de esta manera, puedes reducir drásticamente el tiempo que tardas en encontrar una solución. No temas a los errores; siéntete libre de apoyarte en la IA cada vez más.

3 buenos hábitos para prevenir NameErrors antes de que ocurran

La capacidad de resolver errores es importante, pero idealmente, quieres escribir código que no produzca errores en primer lugar. Aquí hay tres hábitos que practico para reducir los `NameError`s.

1. Usa nombres de variables descriptivos

Nombres cortos como `x` o `tmp` son propensos a errores tipográficos y hacen que sea difícil recordar para qué sirve la variable cuando revisas el código más tarde. Recomiendo encarecidamente usar nombres significativos como `user_name` o `total_price`, incluso si son un poco más largos.

2. Usa un Linter

Un linter es una herramienta que señala errores gramaticales y posibles bugs en tu código en tiempo real mientras lo escribes. Editores avanzados como VSCode te permiten agregar fácilmente linters de Python como `Pylint` o `Flake8`. Si intentas usar una variable no definida, el editor te lo notificará con una línea ondulada o un indicador similar antes de que ejecutes el código, lo que puede reducir drásticamente los `NameError`s.

3. Ejecuta tu código con frecuencia

Si ejecutas tu código por primera vez después de escribir 100 líneas, puede ser muy difícil encontrar dónde está el error. Si adquieres el hábito de verificar tu trabajo en pequeños incrementos —ejecutando el código después de escribir unas pocas líneas, o después de crear una sola función— se vuelve mucho más fácil identificar la ubicación de un error.

Conclusión: ¡los errores son una señal de crecimiento!

En este artículo, he explicado las causas y soluciones específicas para el `NameError`, un rito de iniciación para todo principiante, compartiendo mis propias experiencias en el camino.

Repasemos una vez más las tres causas principales del `NameError`:

• Errores tipográficos: La ortografía de un nombre de variable o función es incorrecta.
• Orden de ejecución incorrecto: Intentar usar una variable antes de que haya sido definida.
• El muro del ámbito: Acceder a una variable desde fuera de su rango válido, como intentar usar una variable de dentro de una función en el exterior.

Los mensajes de error son pistas valiosas para hacer que tu código funcione. Cuando te aparezca un `NameError`, solo piensa: "Ah, Python me está diciendo que no conoce un nombre", y busca la causa con calma. Y no olvides que tienes un poderoso compañero en la IA cuando te quedes atascado.

Cada vez que superas un error, tus habilidades de programación mejoran definitivamente. Los errores no son algo a lo que temer; son los mejores maestros que te ayudan a crecer. ¡Sigamos disfrutando de la programación juntos!