Convertir un archivo de Python en un ejecutable
Este manual explica cómo tomar un archivo .py, convertirlo en un programa ejecutable desde la terminal y poder lanzarlo sin escribir python3 delante.
1. Punto de partida
Partimos de un archivo Python normal, por ejemplo saludo.py:
# saludo.py
print("Hola, mundo")Se puede ejecutar así:
python3 saludo.pyEl objetivo es poder ejecutarlo de estas dos formas:
./saludo.py # desde el directorio donde está el archivo
saludo.py # desde cualquier directorio (si está en el PATH)2. El shebang (#!)
El shebang (o hashbang) es una línea especial que se coloca en la primera línea del archivo y le dice al sistema operativo qué intérprete debe usar para ejecutarlo.
#!/usr/bin/env python3
print("Hola, mundo")Reglas importantes:
- Debe ser la primera línea del archivo. No puede haber líneas en blanco ni espacios antes.
- Debe empezar exactamente por
#!. - El archivo debe terminar con un salto de línea.
- Si falta el shebang, al hacer
./saludo.pyel sistema puede intentar ejecutarlo como si fuera un script de shell y fallar.
#!/usr/bin/env python3 o #!/usr/bin/python3
Hay dos formas habituales:
| Shebang | Significado | Recomendación |
|---|---|---|
#!/usr/bin/env python3 | Busca python3 en el PATH del usuario. | Recomendado: funciona aunque Python esté en otra ruta o dentro de un entorno virtual. |
#!/usr/bin/python3 | Usa esa ruta exacta y fija. | Solo si estás seguro de que Python siempre está ahí. |
En la práctica, usa #!/usr/bin/env python3 casi siempre.
3. Dar permisos de ejecución
En Linux y macOS ningún archivo se ejecuta por el simple hecho de tener shebang. Necesita el permiso de ejecución.
Ver los permisos
ls -l saludo.pySalida típica:
-rw-r--r-- 1 diego staff 38 nov 12 10:00 saludo.pyLa primera columna son los permisos, agrupados en tres bloques de tres:
- rwx rwx rwx
│ │ │ └── otros (otros usuarios)
│ │ └─────── grupo
│ └──────────── propietario
└──────────────── tipo de archivo (- archivo, d directorio)Cada letra significa:
| Letra | Permiso | En un archivo | En un directorio |
|---|---|---|---|
r | lectura | leer el contenido | listar su contenido |
w | escritura | modificar el contenido | crear/borrar archivos |
x | ejecución | ejecutarlo como programa | entrar en él (cd) |
- | sin permiso | — | — |
Añadir el permiso de ejecución
chmod +x saludo.pyAhora ls -l mostrará algo como:
-rwxr-xr-x 1 diego staff 38 nov 12 10:00 saludo.pyTambién se puede hacer con notación numérica. Cada permiso vale:
| Permiso | Valor |
|---|---|
r | 4 |
w | 2 |
x | 1 |
Así, chmod 755 saludo.py equivale a rwxr-xr-x:
chmod 755 saludo.py755: propietario puede todo, grupo y otros solo leer y ejecutar. Es lo habitual para scripts.700: solo el propietario puede leer, escribir y ejecutar.
Para quitar el permiso de ejecución (por ejemplo si te equivocaste):
chmod -x saludo.py4. Ejecutar con ./
Una vez tiene shebang y permiso de ejecución:
./saludo.py¿Por qué hace falta ./?
Cuando escribes solo saludo.py, el sistema busca ese nombre solo en los directorios del PATH, no en el directorio actual. El directorio actual (.) no está en el PATH por seguridad: así se evita ejecutar sin querer un programa malicioso que se llame igual que un comando del sistema y esté en la carpeta donde estamos.
Por eso se indica la ruta de forma explícita:
./saludo.py→ archivo en el directorio actual.../saludo.py→ archivo en el directorio padre./home/diego/saludo.py→ ruta absoluta.
Puedes comprobar que . no está en el PATH:
echo $PATH5. Poner el script en el PATH para ejecutarlo sin ./
Si quieres escribir simplemente saludo.py desde cualquier carpeta, el archivo debe estar en un directorio que forme parte del PATH.
Ver el PATH actual
echo $PATHSalida de ejemplo (separada por :):
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/diego/.local/binOpción recomendada: ~/.local/bin o ~/bin
Crea una carpeta personal para tus scripts:
mkdir -p ~/.local/binMueve (o copia) el script allí:
mv saludo.py ~/.local/bin/saludoFíjate que, al ser ejecutable, se le puede quitar la extensión .py. El nombre del comando es el nombre del archivo.
Comprueba que esa carpeta está en el PATH:
echo $PATH | tr ':' '\n' | grep -F "$HOME/.local/bin"Si no aparece, añádela a la configuración de tu shell.
Añadir la carpeta al PATH de forma permanente
El shell lee un archivo de configuración al arrancar. Según el shell:
| Shell | Archivo de configuración |
|---|---|
| zsh (por defecto en macOS) | ~/.zshrc |
| bash | ~/.bashrc (Linux) o ~/.bash_profile (macOS) |
Añade esta línea al final del archivo:
export PATH="$HOME/.local/bin:$PATH"Recarga la configuración (o abre una terminal nueva):
source ~/.zshrc # o source ~/.bashrcVerificar
which saludo
saludowhich muestra la ruta del ejecutable que se usará. Si aparece tu script, ya puedes ejecutarlo escribiendo solo su nombre desde cualquier directorio.
Alternativa: enlace simbólico
Si no quieres mover el archivo, puedes dejarlo donde está y crear un enlace en una carpeta del PATH:
ln -s /ruta/completa/saludo.py ~/.local/bin/saludoAsí el código sigue en su ubicación original pero el comando está disponible en el PATH.
Alternativa: /usr/local/bin
También puedes copiarlo en /usr/local/bin, que suele estar en el PATH del sistema:
sudo cp saludo.py /usr/local/bin/saludo
sudo chmod +x /usr/local/bin/saludoRequiere permisos de administrador y modifica una zona del sistema. Es preferible usar ~/.local/bin para tus propios scripts.
6. Ejemplo completo
# 1. Crear el archivo con el shebang en la primera línea
cat > saludo.py <<'EOF'
#!/usr/bin/env python3
print("Hola, mundo")
EOF
# 2. Dar permiso de ejecución
chmod +x saludo.py
# 3. Ejecutarlo desde el directorio actual
./saludo.py
# 4. Moverlo a una carpeta del PATH y ejecutarlo sin ./
mkdir -p ~/.local/bin
mv saludo.py ~/.local/bin/saludo
saludo7. Comprobar y resolver problemas
| Síntoma | Causa probable | Solución |
|---|---|---|
Permission denied | Falta el permiso de ejecución | chmod +x archivo |
bad interpreter: No such file or directory | El shebang apunta a una ruta que no existe o tiene \r\n de Windows | Usa #!/usr/bin/env python3 y convierte a saltos de línea Unix (dos2unix archivo) |
command not found al escribir solo el nombre | La carpeta no está en el PATH | Añádela al PATH o usa ./nombre |
| Se ejecuta pero no hace nada / error raro | Falta el shebang o no está en la primera línea | Revisa la primera línea del archivo |
SyntaxError | Se está usando un Python distinto al esperado | Comprueba con which python3 y el shebang |
Comandos útiles de diagnóstico:
ls -l archivo # ver permisos
file archivo # ver tipo de archivo
head -1 archivo # ver el shebang
which python3 # ruta del intérprete
command -v archivo # comprobar si el comando está en el PATH8. Nota sobre Windows
Windows no usa shebang ni permisos de ejecución de la misma forma. Allí se ejecuta con:
py saludo.pyo configurando la asociación de archivos .py. Para obtener un .exe real se usan herramientas como PyInstaller:
pyinstaller --onefile saludo.pyEste manual se centra en Linux y macOS, donde el concepto de shebang, permisos y PATH es el habitual.
9. Resumen
- Añade
#!/usr/bin/env python3en la primera línea del archivo. - Da permisos con
chmod +x archivo. - Ejecuta con
./archivodesde su carpeta. - Para ejecutarlo desde cualquier sitio, muévelo a una carpeta del
PATH(por ejemplo~/.local/bin) y asegúrate de que esa carpeta está enexport PATH. - Comprueba con
which nombreyls -l.
