Si estás aprendiendo Python, probablemente en algún momento necesitarás compartir una variable entre diferentes funciones y te preguntarás cómo hacerlo correctamente. Para ello, es fundamental entender cómo funcionan las variables globales en Python y cuándo necesitas utilizar la palabra clave global.

La buena noticia es que declarar variables globales en Python es bastante sencillo: normalmente solo tienes que crear la variable fuera de cualquier función. Sin embargo, la situación cambia cuando quieres modificar su valor desde el interior de una función.

¿Qué es una variable global en Python?

Una variable global es una variable definida en el ámbito global de un módulo. En términos sencillos, es una variable creada fuera de las funciones y que puede ser consultada desde diferentes partes de ese módulo.

Por ejemplo:

nombre = "Ana"

def saludar():
    print(f"Hola, {nombre}")

saludar()
print(nombre)

En este código, nombre es una variable global porque fue definida fuera de saludar().

Por eso podemos acceder a ella tanto desde el interior de la función como desde el código que se encuentra fuera de ella.

¿Significa esto que debemos escribir global nombre al crearla? No. Esta es precisamente una de las confusiones más frecuentes cuando alguien comienza a trabajar con variables globales.

Cómo declarar variables globales en Python

Para declarar variables globales en Python, puedes asignarles un valor fuera de cualquier función.

💡 Si estás buscando simplificar tu código y escribir funciones más compactas en pocas líneas, te recomiendo explorar cómo dominar las expresiones lambda en Python para potenciar tu productividad y escribir código más elegante y pythonic.

Por ejemplo:

contador = 0
nombre = "Carlos"
sesion_activa = True

Las tres variables pertenecen al ámbito global del módulo.

No necesitas escribir:

global contador
contador = 0

cuando estás trabajando directamente en el ámbito global.

Una declaración sencilla como esta es suficiente:

contador = 0

La ubicación de la variable determina su ámbito.

Veamos otro ejemplo:

precio = 100

def mostrar_precio():
    print(precio)

mostrar_precio()

El resultado será:

100

La función puede leer la variable global precio aunque no hayamos utilizado la palabra clave global.

Aquí aparece una pregunta importante: entonces, ¿para qué existe global?

¿Para qué sirve global en Python?

La palabra clave global le indica a Python que un nombre utilizado dentro de una función hace referencia al nombre correspondiente del ámbito global.

Esto resulta especialmente importante cuando queremos reasignar una variable global desde una función.

Observa este ejemplo:

contador = 0

def incrementar():
    global contador
    contador += 1

incrementar()

print(contador)

El resultado será:

1

Dentro de incrementar() escribimos:

global contador

De esta forma indicamos que la asignación posterior debe trabajar con el contador global y no con una nueva variable local.

Esta diferencia parece pequeña, pero es fundamental para comprender correctamente el alcance de las variables en Python.

Sintaxis de global en Python

La sintaxis básica es:

global nombre_variable

Después puedes trabajar con esa variable dentro de la función:

puntos = 0

def agregar_puntos():
    global puntos
    puntos = puntos + 10

También puedes especificar varios nombres en una misma declaración:

global puntos, nivel, vidas

Por ejemplo:

puntos = 0
nivel = 1
vidas = 3

def reiniciar():
    global puntos, nivel, vidas

    puntos = 0
    nivel = 1
    vidas = 3

Aunque Python permite hacerlo, tener muchas variables globales modificándose desde diferentes funciones puede convertirse rápidamente en un problema de mantenimiento.

Más adelante veremos alternativas a global que pueden resultar más apropiadas.

Leer una variable global desde una función

Una característica importante de Python es que no necesitas global simplemente para consultar el valor de una variable global.

💡 Si estás buscando crear videojuegos o aplicaciones multimedia en Python de forma ágil y sin complicaciones, te recomiendo descubrir qué es Pyglet y cuáles son sus ventajas principales, una biblioteca que destaca por su simplicidad y potencia para proyectos gráficos interactivos.

Por ejemplo:

lenguaje = "Python"

def mostrar_lenguaje():
    print(lenguaje)

mostrar_lenguaje()

Obtendremos:

Python

No hemos utilizado:

global lenguaje

porque únicamente estamos leyendo su valor.

Otro ejemplo:

precio_base = 100

def calcular_precio():
    return precio_base * 1.13

print(calcular_precio())

La función puede consultar precio_base sin ningún problema.

Esta regla puede resumirse de una manera sencilla:

Leer una variable global: normalmente no requiere global.

Reasignar una variable global dentro de una función: requiere global.

Recordar esta diferencia te evitará muchos errores.

Cómo modificar una variable global en Python

Supongamos que estamos creando un pequeño contador:

contador = 0

def incrementar():
    global contador
    contador += 1

incrementar()
incrementar()
incrementar()

print(contador)

El resultado será:

3

Cada llamada a incrementar() modifica el mismo contador.

Ahora eliminemos global:

contador = 0

def incrementar():
    contador += 1

incrementar()

El programa producirá un error similar a:

UnboundLocalError

¿Por qué ocurre?

Python detecta que dentro de la función existe una asignación relacionada con contador.

Por ello interpreta contador como un nombre local de esa función. Sin embargo, la expresión:

contador += 1

necesita conocer primero el valor de contador.

En términos simplificados, es parecido a intentar hacer:

contador = contador + 1

pero el contador local todavía no tiene un valor.

Al escribir:

global contador

le indicamos a Python que queremos trabajar con el nombre existente en el ámbito global.

Diferencia entre variable local y global

Comprender la diferencia entre variables locales y globales es esencial para evitar errores.

Una variable local se crea dentro de una función:

def calcular():
    resultado = 10 * 5
    print(resultado)

calcular()

resultado pertenece al ámbito local de calcular().

Si intentamos hacer esto:

def calcular():
    resultado = 10 * 5

calcular()

print(resultado)

obtendremos un NameError, porque resultado no existe en el ámbito desde el que intentamos acceder a ella.

En cambio:

resultado = 50

def mostrar():
    print(resultado)

mostrar()
print(resultado)

funciona porque resultado está definido en el ámbito global.

Podemos verlo rápidamente en esta tabla:

Característica	Variable local	Variable global
Se define normalmente	Dentro de una función	Fuera de las funciones
Puede leerse dentro de su función	Sí	Sí
Puede consultarse desde otras funciones	No directamente	Sí, si está en el ámbito accesible
Reasignarla desde una función requiere global	No	Sí
Alcance	Local	Módulo

Variable global y local con el mismo nombre

Python permite tener una variable global y otra local con el mismo nombre.

Por ejemplo:

nombre = "Ana"

def cambiar_nombre():
    nombre = "Carlos"
    print(nombre)

cambiar_nombre()

print(nombre)

El resultado será:

Carlos
Ana

Puede parecer extraño inicialmente.

La variable:

nombre = "Carlos"

es local a cambiar_nombre().

Por tanto, no modifica la variable global:

nombre = "Ana"

Si realmente queremos cambiarla, necesitamos:

nombre = "Ana"

def cambiar_nombre():
    global nombre
    nombre = "Carlos"

cambiar_nombre()

print(nombre)

Ahora obtenemos:

Carlos

La declaración global nombre hace que la asignación realizada dentro de la función afecte al nombre del ámbito global.

Ejemplo práctico: contador global

Uno de los ejemplos más fáciles para entender global es un contador:

visitas = 0

def registrar_visita():
    global visitas
    visitas += 1

def mostrar_visitas():
    print(f"Visitas: {visitas}")

registrar_visita()
registrar_visita()
registrar_visita()

mostrar_visitas()

Obtendremos:

Visitas: 3

Observa un detalle interesante.

registrar_visita() necesita:

global visitas

porque modifica el nombre.

En cambio, mostrar_visitas() solamente consulta su valor y por eso no necesita global.

Ejemplo con una sesión de usuario

Veamos una situación algo más cercana a una aplicación real:

usuario_actual = None
sesion_activa = False

def iniciar_sesion(nombre):
    global usuario_actual, sesion_activa

    usuario_actual = nombre
    sesion_activa = True

def cerrar_sesion():
    global usuario_actual, sesion_activa

    usuario_actual = None
    sesion_activa = False

iniciar_sesion("Ana")

print(usuario_actual)
print(sesion_activa)

cerrar_sesion()

print(usuario_actual)
print(sesion_activa)

Aquí tenemos dos variables globales cuyo estado cambia dependiendo de las funciones que ejecutemos.

Es un ejemplo útil para aprender, aunque en una aplicación grande probablemente sería mejor encapsular este estado dentro de una clase u otra estructura.

Declarar varias variables globales en Python

Puedes trabajar con múltiples nombres globales dentro de una misma función.

Por ejemplo:

nombre = ""
edad = 0
activo = False

def configurar_usuario():
    global nombre, edad, activo

    nombre = "Laura"
    edad = 28
    activo = True

También podrías escribir:

global nombre
global edad
global activo

pero normalmente resulta más compacto:

global nombre, edad, activo

Eso sí, si una función necesita modificar diez o quince variables globales, probablemente el problema ya no sea la sintaxis.

Quizás sea momento de reconsiderar cómo estás estructurando el programa.

El error UnboundLocalError y las variables globales

Uno de los errores más relacionados con este tema es UnboundLocalError.

Imagina:

total = 100

def aumentar_total():
    total = total + 50

aumentar_total()

Podrías pensar que Python utilizará automáticamente el total global.

Sin embargo, como dentro de la función existe una asignación:

total = total + 50

Python trata ese nombre como local dentro de la función.

El problema es que intentamos leer su valor antes de que esa variable local tenga uno asignado.

La solución, si realmente queremos modificar el estado global, sería:

total = 100

def aumentar_total():
    global total
    total = total + 50

aumentar_total()

print(total)

Ahora obtenemos:

150

Entender este comportamiento es mucho más importante que simplemente memorizar dónde colocar global.

¿Se puede crear una variable global desde una función?

Sí, técnicamente es posible asociar un nombre al ámbito global desde una función utilizando global.

Por ejemplo:

def crear_variable():
    global mensaje
    mensaje = "Hola desde Python"

crear_variable()

print(mensaje)

El resultado será:

Hola desde Python

Sin embargo, aunque funciona, generalmente resulta más claro definir primero el nombre en el ámbito global cuando forma parte del estado esperado del programa:

mensaje = None

def cambiar_mensaje():
    global mensaje
    mensaje = "Hola desde Python"

De esta manera, cualquier persona que lea el archivo puede identificar fácilmente qué estado global existe sin tener que investigar qué función lo crea.

Variables globales mutables: un detalle importante

Aquí encontramos un comportamiento que suele generar confusión.

Supongamos que tenemos una lista:

usuarios = []

def agregar_usuario(nombre):
    usuarios.append(nombre)

agregar_usuario("Ana")
agregar_usuario("Carlos")

print(usuarios)

El resultado será:

['Ana', 'Carlos']

¿Notaste algo?

No utilizamos:

global usuarios

Esto ocurre porque no estamos reasignando el nombre usuarios. Estamos modificando el objeto mutable al que ese nombre hace referencia.

Lo mismo puede ocurrir con un diccionario:

configuracion = {
    "debug": False
}

def activar_debug():
    configuracion["debug"] = True

activar_debug()

print(configuracion)

Obtendremos:

{'debug': True}

Pero si intentamos reasignar el nombre completo:

configuracion = {
    "debug": False
}

def cambiar_configuracion():
    configuracion = {
        "debug": True
    }

esa nueva configuracion será local.

Para reasignar el nombre global necesitaríamos:

def cambiar_configuracion():
    global configuracion

    configuracion = {
        "debug": True
    }

La diferencia entre mutar un objeto y reasignar un nombre es muy importante cuando trabajas con el alcance de variables en Python.

¿Qué diferencia hay entre global y nonlocal?

Otra palabra que puedes encontrar mientras aprendes Python es nonlocal.

No significan lo mismo.

global trabaja con nombres del ámbito global del módulo.

nonlocal, por otro lado, se utiliza principalmente con funciones anidadas para referirse a un nombre perteneciente a una función externa que no es el ámbito global.

Por ejemplo:

def contador():
    numero = 0

    def incrementar():
        nonlocal numero
        numero += 1
        return numero

    return incrementar

incrementar = contador()

print(incrementar())
print(incrementar())
print(incrementar())

Obtendremos:

1
2
3

Aquí numero no es global.

Pertenece al ámbito de contador(), y la función interna utiliza nonlocal para modificar ese nombre.

Una forma rápida de recordarlo es:

• global: ámbito global del módulo.
• nonlocal: ámbito envolvente de una función.
• variable local: ámbito de la función actual.

Variables globales entre diferentes archivos de Python

En proyectos reales es habitual dividir el código en varios módulos.

Por ejemplo, podríamos crear:

config.py
main.py

En config.py:

DEBUG = False
MAX_INTENTOS = 3
API_URL = "https://ejemplo.com"

Y desde main.py:

import config

print(config.MAX_INTENTOS)
print(config.API_URL)

Esta estrategia puede ser útil para mantener configuraciones compartidas en un lugar claramente identificado.

También hace explícito de dónde proviene cada valor:

config.MAX_INTENTOS

en lugar de tener numerosos nombres globales repartidos por diferentes archivos.

Para constantes de configuración, además, es habitual utilizar nombres en mayúsculas:

MAX_INTENTOS = 3
TIEMPO_ESPERA = 30

La mayúscula es una convención de nombres que comunica al programador que ese valor está pensado como constante, aunque Python no impide técnicamente modificarlo.

¿Es malo utilizar variables globales en Python?

No necesariamente.

Las variables globales existen porque hay situaciones donde pueden resultar útiles. El problema aparece cuando se convierten en la forma predeterminada de compartir información entre todas las funciones.

Imagina un programa con:

usuario = None
saldo = 0
contador = 0
estado = ""
configuracion = {}
errores = []
sesion = False

y treinta funciones capaces de modificar esos valores.

Cuando aparezca un error tendrás que descubrir qué función modificó determinada variable y en qué momento ocurrió.

No parece muy divertido, ¿verdad?

El abuso del estado global puede provocar:

• Dependencias ocultas entre funciones.
• Código más difícil de probar.
• Efectos secundarios inesperados.
• Mayor dificultad para encontrar errores.
• Funciones menos reutilizables.
• Código más complicado de mantener.

Por eso global debe utilizarse cuando realmente aporta simplicidad, no simplemente para evitar pasar argumentos entre funciones.

Alternativa 1: retornar valores

En muchos casos puedes evitar una variable global simplemente retornando el nuevo valor.

En lugar de:

contador = 0

def incrementar():
    global contador
    contador += 1

puedes escribir:

def incrementar(contador):
    return contador + 1

contador = 0
contador = incrementar(contador)
contador = incrementar(contador)

print(contador)

Obtendremos:

2

La función ahora recibe explícitamente lo que necesita y devuelve su resultado.

Esto hace que su comportamiento sea más fácil de entender y probar.

Alternativa 2: pasar variables como argumentos

Otra posibilidad consiste simplemente en pasar los datos necesarios:

def calcular_total(precio, cantidad, descuento):
    subtotal = precio * cantidad
    return subtotal * (1 - descuento)

resultado = calcular_total(100, 3, 0.10)

print(resultado)

No necesitamos ninguna variable global.

Además, sabemos exactamente cuáles son las dependencias de la función observando sus parámetros.

Alternativa 3: utilizar una clase

Cuando diferentes funciones necesitan modificar un mismo estado, una clase puede ser una solución más organizada.

Por ejemplo:

class Contador:
    def __init__(self):
        self.valor = 0

    def incrementar(self):
        self.valor += 1

    def reiniciar(self):
        self.valor = 0

contador = Contador()

contador.incrementar()
contador.incrementar()

print(contador.valor)

Obtendremos:

2

Ahora el estado pertenece al objeto contador.

En proyectos más grandes, esta estructura suele ser más sencilla de mantener que tener numerosas variables globales modificables.

Alternativa 4: agrupar configuraciones

Si necesitas compartir configuraciones, puedes agruparlas:

config = {
    "debug": False,
    "timeout": 30,
    "max_reintentos": 3
}

Después puedes pasar esa configuración donde sea necesaria:

def procesar(config):
    if config["debug"]:
        print("Modo debug activado")

    print(f"Timeout: {config['timeout']}")

Esto evita tener variables como:

debug = False
timeout = 30
max_reintentos = 3

repartidas por diferentes lugares del programa.

Errores comunes al declarar variables globales en Python

Aunque la sintaxis de global es sencilla, existen algunos errores que aparecen constantemente.

Usar global fuera de una función pensando que es obligatorio

No necesitas hacer esto:

global contador
contador = 0

para convertir contador en global.

Simplemente:

contador = 0

en el ámbito del módulo ya crea el nombre allí.

Olvidar global cuando reasignas una variable

Este código falla:

contador = 0

def incrementar():
    contador += 1

Si quieres modificar el nombre global:

contador = 0

def incrementar():
    global contador
    contador += 1

Utilizar global cuando solamente quieres leer

Esto funciona:

mensaje = "Hola"

def mostrar():
    print(mensaje)

No hace falta agregar global mensaje.

Confundir una variable local con la global

Observa:

numero = 10

def cambiar():
    numero = 20

La variable global continúa teniendo el valor 10.

Si quieres reasignarla:

numero = 10

def cambiar():
    global numero
    numero = 20

Utilizar demasiadas variables globales

Que Python permita algo no significa que debas utilizarlo en todas partes.

Si constantemente estás escribiendo:

global ...

en muchas funciones, puede ser una señal de que necesitas reorganizar el diseño del programa.

Buenas prácticas al utilizar global

Si necesitas utilizar global, existen algunas prácticas que pueden ayudarte a mantener el código comprensible.

Primero, intenta reducir su uso. Una o dos variables globales controladas son muy diferentes de tener decenas modificándose desde cualquier función.

Segundo, utiliza nombres descriptivos:

total_usuarios = 0

es mucho mejor que:

x = 0

También conviene mantener las variables globales importantes en una zona fácilmente identificable del módulo.

Por ejemplo:

MAX_INTENTOS = 3
contador_errores = 0
modo_debug = False

Finalmente, antes de utilizar global, pregúntate:

¿Esta función realmente necesita modificar estado externo?

Si puedes resolver el problema retornando un valor o pasando un argumento sin complicar el código, probablemente esa alternativa sea preferible.

¿Cuándo conviene utilizar variables globales?

Las variables globales pueden ser razonables para valores compartidos sencillos, pequeñas herramientas, scripts cortos o determinados estados controlados.

También es habitual encontrar valores globales utilizados como constantes del módulo:

PI = 3.141592653589793
MAX_CONEXIONES = 10
NOMBRE_APP = "Mi aplicación"

En este caso no estamos utilizando global para modificar constantemente esos valores.

Simplemente tenemos información disponible a nivel del módulo.

Para aplicaciones grandes, en cambio, suele ser conveniente utilizar argumentos, valores de retorno, clases, objetos de configuración u otras formas de manejar el estado.

Preguntas frecuentes sobre variables globales en Python

¿Cómo declarar una variable global en Python?

Normalmente basta con definirla fuera de cualquier función:

nombre = "Python"

Ese nombre pertenece al ámbito global del módulo.

¿Tengo que usar global para crear una variable global?

No cuando la defines directamente en el ámbito global.

La palabra clave global se utiliza dentro de una función cuando necesitas que las asignaciones a determinado nombre se realicen sobre el nombre global.

¿Puedo leer una variable global sin usar global?

Sí:

nombre = "Python"

def mostrar():
    print(nombre)

Como la función solamente consulta el valor, no necesita global.

¿Cómo cambiar una variable global dentro de una función?

Utiliza global antes de realizar la asignación:

contador = 0

def cambiar():
    global contador
    contador = 10

Después de ejecutar cambiar(), contador tendrá el valor 10.

¿Puedo declarar varias variables con global?

Sí:

global nombre, edad, activo

Esto indica que esos nombres deben resolverse en el ámbito global cuando se utilicen dentro de esa función.

¿Cuál es la diferencia entre global y nonlocal?

global hace referencia al ámbito global del módulo, mientras que nonlocal permite trabajar con nombres de un ámbito envolvente en funciones anidadas.

Son conceptos relacionados con el alcance, pero resuelven situaciones diferentes.

¿Es recomendable usar global en Python?

Puede utilizarse, pero conviene hacerlo con moderación.

En programas pequeños puede resultar práctico. En aplicaciones grandes, abusar del estado global suele dificultar las pruebas, el mantenimiento y la comprensión del código.

Conclusión

Declarar variables globales en Python es más sencillo de lo que puede parecer: una variable definida en el ámbito superior de un módulo ya pertenece a su ámbito global y puede ser consultada desde las funciones que tengan acceso a ella.

La palabra clave global entra en juego principalmente cuando una función necesita reasignar un nombre global. Por ejemplo:

contador = 0

def incrementar():
    global contador
    contador += 1

La clave está en no confundir declarar una variable global con utilizar la declaración global. Son conceptos relacionados, pero no exactamente lo mismo.

Una vez que comprendes la diferencia entre variables locales, globales y nonlocal, errores como UnboundLocalError dejan de parecer misteriosos y resulta mucho más fácil decidir cuándo utilizar global.

Y recuerda: si necesitas declarar global en prácticamente todas tus funciones, quizá Python no sea quien te está pidiendo más global; quizá tu código te está pidiendo una pequeña reorganización.