Cómo instalar Osintgram en 2026

Antes de empezar

Necesitas un intérprete de Python 3, git y haber decidido cómo va a autenticarse Osintgram. Lo tercero es lo que la gente se salta, y es la razón por la que la instalación parece funcionar y luego la herramienta se cierra tras una sola línea en la primera ejecución.

El README no indica en ningún momento una versión mínima de Python: lleva una insignia de Python3 y nada más. El único pin de versión que hay en el repositorio es la primera línea del Dockerfile, FROM python:3.9.2-alpine3.13, y la dependencia más reciente, hikerapi 1.7.1, declara requires_python >=3.8. Instalar requirements.txt en un entorno virtual nuevo de Python 3.11 funciona con un pip actual: prettytable 0.7.2, pyreadline 2.1 y hikerapi 1.7.1 se distribuyen solo como código fuente, y los tres se compilan sin quejarse. Considera 3.9–3.11 el punto dulce, no un requisito.

• Python 3.9 a 3.11. Es en 3.12 y 3.13 donde se concentran los fallos reportados, y casi siempre se trata de una colisión de empaquetado, no de una incompatibilidad del lenguaje.
• git, o un ZIP de la rama master. No hay paquete en PyPI ni script de instalación: el repositorio no contiene ningún setup.sh.
• Un compilador y las cabeceras de ncurses en Linux, pero solo si pip tiene que compilar gnureadline. En las distribuciones glibc habituales encuentra un wheel manylinux y se salta la compilación.
• Credenciales. O una cuenta de Instagram que estés dispuesto a perder, o un token de HikerAPI. Decídelo antes del paso seis: llevan a dos rutas de código distintas.

Una plataforma tiene página propia, porque tanto su intérprete por defecto como su pip se comportan de forma distinta a un Debian o un Ubuntu de serie: Osintgram en Kali Linux.

Los seis comandos

Esta es la propia secuencia del README, sin cambios. Ejecútala entera desde una misma shell: tanto el entorno virtual como el directorio de trabajo importan más adelante.

1. 1

   Clona el repositorio

   La rama por defecto es master. También existen las ramas development y v2; ignora las dos salvo que sepas por qué las quieres.

   git clone https://github.com/Datalux/Osintgram.git

2. 2

   Entra en el directorio

   No solo para este paso. Osintgram lee su configuración a través de la ruta relativa config/credentials.ini, así que la raíz del repositorio es el único directorio desde el que funciona correctamente.

   cd Osintgram

3. 3

   Crea un entorno virtual

   En Debian, Ubuntu y Kali puede que antes necesites sudo apt install python3-venv. Saltarse este paso es lo que produce los tres primeros errores de la tabla de más abajo.

   python3 -m venv venv

4. 4

   Actívalo

   Tu prompt debería quedar ahora con el prefijo (venv). Si no es así, el siguiente comando instalará en el intérprete equivocado.

   # Linux, macOS, Git Bash
   source venv/bin/activate
   
   # Windows PowerShell
   .\venv\Scripts\activate.ps1

5. 5

   Instala las dependencias

   El flag es -r. Escribir -t en su lugar te da ERROR: Target path exists but is not a directory, will not continue., porque -t significa --target.

   pip install -r requirements.txt

6. 6

   Rellena tus credenciales

   Edita el archivo INI a mano, o deja que el Makefile te lo pregunte. No son equivalentes: la siguiente sección explica por qué.

   nano config/credentials.ini
   
   # or, with GNU make and bash available:
   make setup

requests-toolbelt==0.9.1
geopy>=2.0.0
prettytable==0.7.2
instagram-private-api==1.6.0
gnureadline>=8.0.0; platform_system != "Windows"
pyreadline==2.1; platform_system == "Windows"
hikerapi==1.7.1

Dos ausencias en ese archivo te van a confundir después. requests no aparece; llega de forma transitiva. Tampoco httpx, que src/Osintgram.py importa en la línea 9: solo se resuelve porque hikerapi depende de él.

Configurar las credenciales

El repositorio incluye config/credentials.ini ya creado y en blanco. Tres campos, una sección:

[Credentials]
username =
password =
hikerapi_token =

src/config.py lo carga con configparser y la llamada literal config.read("config/credentials.ini"). Esa ruta relativa es la razón de ser del paso dos: lanza python3 ~/Osintgram/main.py sometarget desde tu carpeta personal y configparser no leerá nada, en silencio.

Deja el archivo tal y como viene y la primera ejecución se detiene de inmediato. Con el credentials.ini en blanco de un clon nuevo, main.py imprime una línea y nada más: Error: "username" field cannot be blank in "config/credentials.ini". Junto a ella están hardcodeados el mismo mensaje para password, además de Error: missing "username" field in "config/credentials.ini" y Error: file "config/credentials.ini" not found!.

Qué escribe realmente `make setup`

El target setup del Makefile es corto y hace más de lo que anuncia. Pregunta Instagram Username: con read -p e Instagram Password: con read -sp, así que solo se oculta la contraseña, y después escribe el archivo él mismo. Tres consecuencias no documentadas. Sobrescribe credentials.ini únicamente con [Credentials], username y password, así que cualquier hikerapi_token que tuvieras desaparece. Antes ejecuta echo -n "{}" > config/settings.json, borrando cualquier sesión en caché. Y declara SHELL := /bin/bash y usa read -sp, por lo que necesita GNU make y bash: no se ejecutará en cmd ni en PowerShell.

El campo hikerapi_token

Ese tercer campo cambia qué programa estás ejecutando. src/config.py expone getHikerToken(), que devuelve el valor de hikerapi_token o la variable de entorno HIKERAPI_TOKEN. main.py se bifurca en función de eso: con token construye HikerCLI, y solo en caso contrario el cliente clásico Osintgram. Con un token configurado, la herramienta nunca crea un cliente de Instagram ni envía una contraseña a ninguna parte: no necesitas cuenta de Instagram en absoluto. La línea de arranque pasa a ser Connect to HikerAPI... en lugar de Attempt to login....

HIKERAPI_TOKEN=<hikerapi token> python3 main.py <target> -c info

El README apunta a hikerapi.com/tokens y dice que las "first 100 requests are free after registration and confirmation of your tg" (las primeras 100 peticiones son gratuitas tras el registro y la confirmación de tu tg). A partir de ahí es una API de terceros de pago, y cada nombre de usuario que consultes pasa por ella. Ese es el trato. Es la vía que todavía está pensada para funcionar, y los usuarios reportan que funciona, pero la issue abierta #2664 (21 de junio de 2026) existe precisamente para gestionar formatos alternativos de respuesta de HikerAPI.

Comprueba que ha funcionado

Dos comprobaciones, en este orden: la primera demuestra que el árbol de dependencias se ha resuelto, la segunda que la herramienta puede leer tu configuración. Ejecuta las dos desde la raíz del repositorio con el entorno virtual activo.

cd Osintgram
source venv/bin/activate

# 1. does the package tree import?
python -c "from src.Osintgram import Osintgram; print('ok')"

# 2. does it read your credentials and reach login?
python3 main.py <target username> --command info

Si la primera imprime ok, tu instalación ha terminado. Si la segunda imprime un error de campo en blanco, vuelve a la sección de credenciales. Si imprime Attempt to login... o Connect to HikerAPI..., la instalación está hecha y todo lo que venga después de esa línea es problema de Instagram.

Una más para adelantarnos: ModuleNotFoundError: No module named 'src.Osintgram' significa que lanzaste main.py desde algún sitio que no es la raíz del repositorio. Esa es la issue #105, y la solución es cd Osintgram, siempre.

Errores de instalación y qué significan en realidad

Todas las cadenas de la columna izquierda salen del gestor de incidencias del proyecto o se han reproducido en local sobre un clon limpio. Ninguna es del lado de Instagram: todas ocurren antes de que salga una sola petición de tu máquina.

Las tres primeras filas solo ocurren cuando pip se ejecuta contra el intérprete del sistema, así que desaparecen en cuanto usas de verdad el entorno virtual. Por eso el paso tres no es un trámite decorativo.

Windows y WSL

En Windows nativo la instalación de dependencias va bien. Clonar master e instalar requirements.txt en un entorno virtual de Python 3.11 funciona, y el pyreadline 2.1 exclusivo de Windows se compila desde el código fuente sin errores. Lo que falla es justo lo siguiente, antes incluso de que argparse haya leído tus argumentos:

File "...\Osintgram\main.py", line 108, in <module>
    pyreadline.Readline().parse_and_bind("tab: complete")
  File "...\pyreadline\py3k_compat.py", line 8, in callable
    return isinstance(x, collections.Callable)
AttributeError: module 'collections' has no attribute 'Callable'

collections.Callable se eliminó en Python 3.10 y se movió a collections.abc; la última versión publicada de pyreadline 2.1 es de 2020. main.py llega a esa línea porque su import de readline es un try: import gnureadline / except: import pyreadline, y requirements.txt instala pyreadline solo en Windows, así que Windows es la única vía que toca el módulo roto.

Cuatro cosas que sí funcionan:

1. Parchea pyreadline. En venv\Lib\site-packages\pyreadline\py3k_compat.py, cambia el collections.Callable de la línea 8 por collections.abc.Callable. Verificado: main.py llega entonces hasta la comprobación de credenciales.
2. Parchea main.py en su lugar. Cambia el fallback por import pyreadline3 as pyreadline. Mismo resultado, pero es una modificación de código versionado con la que git pull te va a pelear.
3. Usa WSL. Dentro de una shell de WSL con Ubuntu o Debian estás en la vía Linux: el marcador de entorno selecciona gnureadline, pyreadline no se instala nunca y los mismos seis comandos valen al pie de la letra. PEP 668 también aplica ahí, así que mantén el entorno virtual.
4. Usa Python 3.9 en Windows, donde collections.Callable todavía existe. Funciona, pero envejece mal.

WSL es la recomendación honesta: todas las rutas de código, todos los tracebacks del gestor de incidencias y el propio contenedor del proyecto dan por hecho Linux. Git Bash es un término medio parcial (el README documenta source venv/bin/activate para él), pero sigue ejecutando el intérprete de Windows, así que sigue chocando con la línea 108.

Docker

El repositorio incluye un Dockerfile, un docker-compose.yml y un Makefile. Docker es la única vía que esquiva por completo la cuestión de la versión de Python, porque la imagen fija su propio intérprete.

make setup
docker build -t osintgram .
docker run --rm -it \
  -v "$PWD/output:/home/osintgram/output" osintgram <target>

Dos datos más sobre Docker. La imagen base es python:3.9.2-alpine3.13, una build de marzo de 2021, que es exactamente la razón por la que el contenedor esquiva las colisiones de 3.12 y 3.13, y también por la que es lo menos parcheado que tienes en la máquina. Y los targets run, build-run-testing y cleanup-testing del Makefile llaman todos a docker-compose, el binario v1 con guion que las instalaciones modernas de Docker ya no incluyen.

Mitos que te hacen perder el tiempo

Hay cuatro afirmaciones que aparecen una y otra vez en las guías de instalación de Osintgram. Las cuatro se pueden contrastar con el código fuente, y las cuatro son falsas.

• "Python 3.12 eliminó distutils, así que Osintgram no se puede instalar." El setup.py de prettytable 0.7.2 empieza con from setuptools import setup: no hay ni un import de distutils en todo el archivo, y el aislamiento de build por defecto de pip provisiona su propio setuptools. El gestor de incidencias entero contiene una sola mención a distutils, y el traceback real de esa issue es un error de expiración de cookies.
• "Necesitas geckodriver, Selenium o Pillow." Buscar con grep en src/Osintgram.py (el motor entero, sus 60,586 bytes) los términos selenium, geckodriver, webdriver, Pillow o PIL devuelve cero coincidencias. No hay capa de automatización de navegador: la herramienta habla HTTP con la API móvil privada de Instagram, y con HikerAPI vía httpx. Las descargas usan urllib.request.urlretrieve.
• "Basta con ejecutar sudo apt install osintgram." Debian no empaqueta Osintgram, y el catálogo de herramientas de Kali tampoco. Tampoco hay paquete en PyPI, así que clonar el repositorio es el único canal de distribución.
• "Edita config.py y pon ahí tus credenciales." No existe ningún config.py en la raíz del repositorio. Existe src/config.py, que es código que no debes tocar; las credenciales viven en config/credentials.ini.

Y un quinto: python3 main.py a secas no arranca nada. argparse declara id como posicional obligatorio, así que lo que obtienes es usage: main.py [-h] [-C] [-j] [-f] [-c COMMAND] [-o OUTPUT] id y una salida. Osintgram no se puede lanzar sin un nombre de usuario objetivo.

Se ha instalado, pero el login falla

El fallo de login es el mayor bloqueo práctico en 2026, y no es un problema de instalación. Tu instalación terminó en el momento en que pip acabó y la comprobación de importación pasó. Todo lo que se imprime después de Attempt to login... pertenece a Instagram.

La issue #2627, abierta el 4 de marzo de 2026, reporta ClientError checkpoint_required con un checkpoint_url de https://i.instagram.com/web/unsupported_version/: es Instagram rechazando la versión de la API de la librería, no tu contraseña. La issue #2630 (2 de abril de 2026) reporta ClientError Bad Request: block_eu_user_login_in_old_app. El autor de la PR #2660 describe la respuesta bad_password como "actually a bot detection, not wrong password" (en realidad es una detección de bots, no una contraseña incorrecta). Ningún comando de pip arregla nada de esto; el panorama completo está en ¿Sigue funcionando Osintgram en 2026?.

Si lo que has conseguido es una shell funcionando, lo siguiente que querrás es la referencia de comandos: qué devuelve cada uno, dónde acaba la salida y cuáles hacen que te limiten. Eso es cómo usar Osintgram. Si tu objetivo es privado, lee antes qué puede y qué no puede hacer Osintgram ahí.