Skip to content

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:

python
# saludo.py
print("Hola, mundo")

Se puede ejecutar así:

bash
python3 saludo.py

El objetivo es poder ejecutarlo de estas dos formas:

bash
./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.

python
#!/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.py el 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:

ShebangSignificadoRecomendación
#!/usr/bin/env python3Busca python3 en el PATH del usuario.Recomendado: funciona aunque Python esté en otra ruta o dentro de un entorno virtual.
#!/usr/bin/python3Usa 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 ​

bash
ls -l saludo.py

Salida típica:

text
-rw-r--r--  1 diego  staff  38 nov 12 10:00 saludo.py

La primera columna son los permisos, agrupados en tres bloques de tres:

text
-  rwx  rwx  rwx
│   │    │    └── otros (otros usuarios)
│   │    └─────── grupo
│   └──────────── propietario
└──────────────── tipo de archivo (- archivo, d directorio)

Cada letra significa:

LetraPermisoEn un archivoEn un directorio
rlecturaleer el contenidolistar su contenido
wescrituramodificar el contenidocrear/borrar archivos
xejecuciónejecutarlo como programaentrar en él (cd)
-sin permiso——

Añadir el permiso de ejecución ​

bash
chmod +x saludo.py

Ahora ls -l mostrará algo como:

text
-rwxr-xr-x  1 diego  staff  38 nov 12 10:00 saludo.py

También se puede hacer con notación numérica. Cada permiso vale:

PermisoValor
r4
w2
x1

Así, chmod 755 saludo.py equivale a rwxr-xr-x:

bash
chmod 755 saludo.py
  • 755: 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):

bash
chmod -x saludo.py

4. Ejecutar con ./ ​

Una vez tiene shebang y permiso de ejecución:

bash
./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:

bash
echo $PATH

5. 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 ​

bash
echo $PATH

Salida de ejemplo (separada por :):

text
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/diego/.local/bin

Opción recomendada: ~/.local/bin o ~/bin ​

Crea una carpeta personal para tus scripts:

bash
mkdir -p ~/.local/bin

Mueve (o copia) el script allí:

bash
mv saludo.py ~/.local/bin/saludo

Fí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:

bash
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:

ShellArchivo 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:

bash
export PATH="$HOME/.local/bin:$PATH"

Recarga la configuración (o abre una terminal nueva):

bash
source ~/.zshrc     # o source ~/.bashrc

Verificar ​

bash
which saludo
saludo

which 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:

bash
ln -s /ruta/completa/saludo.py ~/.local/bin/saludo

Así 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:

bash
sudo cp saludo.py /usr/local/bin/saludo
sudo chmod +x /usr/local/bin/saludo

Requiere permisos de administrador y modifica una zona del sistema. Es preferible usar ~/.local/bin para tus propios scripts.

6. Ejemplo completo ​

bash
# 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
saludo

7. Comprobar y resolver problemas ​

SíntomaCausa probableSolución
Permission deniedFalta el permiso de ejecuciónchmod +x archivo
bad interpreter: No such file or directoryEl shebang apunta a una ruta que no existe o tiene \r\n de WindowsUsa #!/usr/bin/env python3 y convierte a saltos de línea Unix (dos2unix archivo)
command not found al escribir solo el nombreLa carpeta no está en el PATHAñádela al PATH o usa ./nombre
Se ejecuta pero no hace nada / error raroFalta el shebang o no está en la primera líneaRevisa la primera línea del archivo
SyntaxErrorSe está usando un Python distinto al esperadoComprueba con which python3 y el shebang

Comandos útiles de diagnóstico:

bash
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 PATH

8. Nota sobre Windows ​

Windows no usa shebang ni permisos de ejecución de la misma forma. Allí se ejecuta con:

text
py saludo.py

o configurando la asociación de archivos .py. Para obtener un .exe real se usan herramientas como PyInstaller:

text
pyinstaller --onefile saludo.py

Este manual se centra en Linux y macOS, donde el concepto de shebang, permisos y PATH es el habitual.

9. Resumen ​

  1. Añade #!/usr/bin/env python3 en la primera línea del archivo.
  2. Da permisos con chmod +x archivo.
  3. Ejecuta con ./archivo desde su carpeta.
  4. Para ejecutarlo desde cualquier sitio, muévelo a una carpeta del PATH (por ejemplo ~/.local/bin) y asegúrate de que esa carpeta está en export PATH.
  5. Comprueba con which nombre y ls -l.

Publicado bajo la licencia MIT.