---
name: docker_container_running
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "docker_container_running(name: str, timeout: float = 5.0) -> bool"
description: "Comprueba si un contenedor Docker existe y está corriendo. True solo si docker inspect retorna State.Running=true. Cualquier fallo (docker ausente, contenedor inexistente, daemon caído, timeout) devuelve False sin excepción."
tags: [docker, container, infra, healthcheck]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [subprocess]
params:
  - name: name
    desc: "Nombre o ID del contenedor a comprobar. Match exacto, no acepta wildcards."
  - name: timeout
    desc: "Timeout en segundos para `docker inspect`. Default 5.0. Si se supera devuelve False."
output: "True si el contenedor existe y está corriendo. False en cualquier otro caso (no existe, está parado, docker no disponible, timeout)."
tested: true
tests:
  - "True para contenedor en ejecución (mock subprocess)"
  - "False cuando docker inspect retorna 'false'"
  - "False cuando el contenedor no existe (returncode != 0)"
  - "False cuando docker no está instalado (FileNotFoundError)"
  - "False cuando se excede el timeout (TimeoutExpired)"
  - "Integration: comprueba contenedor real si docker disponible"
test_file_path: "python/functions/infra/tests/test_docker_container_running.py"
file_path: "python/functions/infra/docker_container_running.py"
---

## Ejemplo

```python
from python.functions.infra.docker_container_running import docker_container_running

if docker_container_running("better_maps_valhalla"):
    print("Valhalla up")
else:
    print("Valhalla down")
```

## Notas

Wrapper minimalista sobre `docker inspect -f '{{.State.Running}}'`. Pensado como
primitiva componible para verificadores de stack y health checks. No lanza
excepciones — un fallo de cualquier tipo se reporta como False, dejando que
el caller decida qué hacer (skip de test, reintentar, levantar el stack, etc.).