Shebang in Python: sintassi, buone pratiche e alternative moderne

Quando scrivi uno script Python, non stai solo scrivendo codice per l’interprete Python; stai anche indicando al sistema operativo come eseguire quel codice. 

Come vedrai in questo articolo, qualcosa chiamato shebang è importante nei sistemi tipo Unix come Linux e macOS.

Vedrai che gli shebang ti permettono di eseguire direttamente uno script Python, senza digitare esplicitamente python o python3, a patto che il file abbia i permessi di esecuzione. Questo rende gli script più simili a comandi nativi.

Se stai iniziando con Python, ti consiglio di seguire il nostro corso Introduzione a Python, che copre competenze come tipi di dati, liste, funzioni di base e pacchetti.

Cos’è lo shebang in Python?

Uno shebang è una sequenza di caratteri specializzata all’inizio di uno script che indica al sistema operativo quale interprete usare per eseguire il codice. Elimina la necessità di chiamate esplicite all’interprete come python script.py.

Il termine shebang deriva dalla concatenazione dei nomi dei suoi due caratteri principali: il cancelletto # (sharp/hash) e il punto esclamativo ! (bang). Quando questi due caratteri compaiono come i primi due byte di un file (#!), fungono da "numero magico", ovvero una firma che il kernel del sistema usa per identificare il tipo di file e determinare come processarlo.

Lo scopo principale della riga di shebang è specificare quale interprete deve eseguire lo script e come deve essere eseguito. Questo conta nell’uso reale perché spesso nei sistemi sono installate più versioni di Python. Senza shebang, il sistema operativo non ha istruzioni su come eseguire direttamente il file. Per esempio, #!/usr/bin/env python3 invoca l’interprete Python 3.

Lo shebang è stato introdotto nei sistemi Unix-like alla fine degli anni ’70 per standardizzare l’esecuzione degli script tra le diverse shell. Col tempo, questa convenzione è diventata una caratteristica standard dei sistemi operativi Unix-like, inclusi Linux e macOS, e resta alla base della shell scripting e dei linguaggi interpretati come Python, Perl e Ruby.

Come funziona uno shebang in Python?

Vediamo come funziona tecnicamente lo shebang. Quando provi a eseguire uno script, ad esempio ./myscript.py, accade quanto segue:

1. Il kernel del sistema operativo legge i primi byte del file. Se vede il #! come ‘numero magico’, smette di provare a eseguire il file come binario.

2. Il kernel analizza il resto della prima riga per trovare il percorso dell’interprete.

3. L’interprete quindi legge, analizza ed esegue il codice Python.

Spesso vedrai shebang scritti come #!/usr/bin/env python3 invece di un percorso diretto come #!/usr/bin/python3. L’utilità env cerca l’interprete nella variabile d’ambiente PATH del sistema invece di affidarsi a una posizione codificata. Questo approccio rende gli script più portabili, soprattutto tra ambienti virtuali, container o sistemi in cui Python potrebbe essere installato in directory diverse.

In pratica, gli shebang eliminano la necessità di anteporre Python ai comandi e rendono gli script più facili da distribuire e usare.

Sebbene gli shebang siano una funzionalità di base dei sistemi Unix-like, Windows non li supporta nativamente a livello di kernel. Tuttavia, installazioni moderne di Python come il Python Launcher per Windows (py.exe) sono state progettate per leggere le righe di shebang imitando il comportamento Unix e rendendo gli script più compatibili tra piattaforme.

Sintassi e formattazione dello shebang in Python

Uno shebang può sembrare un semplice commento, ma segue regole rigide definite dal sistema operativo. Capire questa struttura è fondamentale per fare in modo che i tuoi script si avviino in modo affidabile nei diversi ambienti.

Struttura e grammatica formali

Uno shebang deve comparire esattamente alla prima riga dello script e iniziare con la sequenza di caratteri #!. È poi seguito dal percorso assoluto dell’interprete:

#!/interpreter/path [optional_argument]Offerto da

Lo shebang deve essere sulla primissima riga del file. Anche una sola riga vuota o uno spazio prima di #! farà sì che il sistema operativo lo ignori, interpretando il file come un normale file di testo.

La maggior parte dei sistemi Unix-like consente un solo argomento e stringhe di argomenti complesse potrebbero non essere analizzate come previsto. Ad esempio, #!/usr/bin/python3 -v funziona, ma aggiungere più flag può portare a comportamenti imprevedibili.

È importante notare che la maggior parte dei sistemi moderni consente una lunghezza massima di circa 127 caratteri sulla riga di shebang, incluso il percorso dell’interprete e gli argomenti. Nello shebang, gli spazi bianchi sono trattati letteralmente, quindi spazi non intenzionali, soprattutto prima di #! o nel percorso dell’interprete, possono interrompere l’esecuzione.

Percorso assoluto vs approcci basati sull’ambiente

Puoi scrivere lo shebang di Python per fare riferimento all’interprete usando un percorso assoluto oppure un approccio basato sull’ambiente. La tabella seguente mostra la differenza tra questi metodi:

Lo sviluppo moderno privilegia #!/usr/bin/env python3, quindi è raccomandato. La Python Enhancement Proposal 394 (PEP 394), che guida la denominazione dei comandi Python, consiglia di usare esplicitamente python3 negli shebang per evitare ambiguità e assicurare che lo script venga eseguito con Python 3 anziché con un obsoleto interprete Python 2.

Estensioni dei file e shebang

Le estensioni dei file hanno un ruolo secondario nell’esecuzione degli script rispetto agli shebang. Nei sistemi Unix-like, uno script non ha bisogno dell’estensione .py per essere eseguito. Se il file ha i permessi di esecuzione e uno shebang valido, può essere eseguito direttamente come qualsiasi altro comando.

Su Windows, le estensioni contano di più poiché l’estensione .py aiuta il sistema operativo ad associare il file all’interprete Python. In pratica, usare l’estensione .py migliora la chiarezza e la compatibilità multipiattaforma. Come buona pratica, dai sempre ai tuoi script un nome del tipo script.py in fase di sviluppo e rimuovi l’estensione per il deployment per garantire che funzionino in modo affidabile nei vari ambienti.

Creare e usare gli shebang negli script Python

Ora che hai capito come funzionano gli shebang, vediamo come implementarli come comandi eseguibili.

Guida passo passo all’implementazione

Per creare uno script Python con shebang per l’esecuzione, segui questi passaggi:

Crea un nuovo file e aggiungi uno shebang come primissima riga. Sotto lo shebang, scrivi il tuo normale codice Python. Salva il file con un’estensione .py facoltativa nei sistemi Unix-like.

#!/usr/bin/env python3
print("This is the churn trends for 2025.")Offerto da

Nei sistemi Unix-like, i file vengono creati senza permessi di esecuzione per impostazione predefinita. Quindi devi concedere i permessi usando il comando chmod (change mode) nel terminale:

chmod +x churn_trendsOfferto da

Esegui lo script facendo riferimento al suo percorso.

./churn_trendsOfferto da

Se vuoi eseguire lo script da qualsiasi posizione senza digitare il percorso, spostalo in una directory già presente nel tuo $PATH come /usr/local/bin oppure aggiungi la cartella del tuo script al PATH:

# Moving the script to a global bin folder
sudo mv churn_trends /usr/local/bin/churn_trendsOfferto da

Combinare shebang con l’idioma name-main

Quando usi uno shebang, intendi sempre che il file venga eseguito come script. Tuttavia, i file Python sono spesso importati come moduli in altri script. Per evitare che la logica del tuo script venga eseguita automaticamente durante un import, dovresti usare il cosiddetto idioma "name-main".

La variabile __name__ è una variabile built-in speciale in cui:

• Se esegui lo script direttamente come ./script.py, Python imposta __name__ su "__main__".

• Se importi lo script usando import script, Python imposta __name__ sul nome del file.

Puoi combinare lo shebang con questo idioma per creare un file che sia sia uno strumento sia una libreria. Nell’esempio sotto, se esegui lo script direttamente, crea un piccolo DataFrame, chiama la funzione e stampa il risultato. Tuttavia, quando importi lo script, è disponibile solo la funzione senza eseguire la logica dello script.

#!/usr/bin/env python3
def analyze_data(df):
    """Reusable function for data processing."""
    return df.describe()

if __name__ == "__main__":
    import pandas as pd
    df = pd.DataFrame({'x': [1, 2, 3]})
    print(analyze_data(df))  # Runs as scriptOfferto da

Buone pratiche per lo shebang in Python

Per assicurarti che i tuoi script con shebang funzionino in modo affidabile attraverso sistemi e scenari di deployment, ti consiglio le seguenti best practice:

Comprendere la specifica della versione di Python

Python 2 e Python 3 differiscono significativamente in sintassi, librerie standard e comportamenti di default. Poiché Python 2 è giunto a fine vita, gli script moderni dovrebbero puntare esplicitamente a Python 3 per evitare ambiguità e problemi imprevisti in fase di esecuzione.

Negli shebang, python, python2 e python3 possono puntare a interpreti diversi a seconda del sistema. Su alcuni sistemi, python può ancora riferirsi a Python 2, mentre su altri potrebbe non esistere affatto. Come raccomandato dalla PEP 394, usa sempre python3 negli shebang per gli script destinati agli utenti, così da rendere esplicita la versione prevista.

#!/usr/bin/env python3Offerto da

Considerazioni speciali per gli ambienti virtuali

Gli ambienti virtuali (venv, conda) isolano le dipendenze del progetto e spesso forniscono il proprio interprete Python. Quando un ambiente virtuale è attivato, la tua shell modifica il PATH. Ad esempio, quando #!/usr/bin/env python3 cerca nel PATH, troverà automaticamente il binario di Python dentro il tuo ambiente virtuale invece della versione di sistema.

Strumenti come pyenv e altri gestori personalizzati dell’interprete funzionano in modo simile manipolando il PATH. Questo rende gli shebang basati sull’ambiente particolarmente efficaci, permettendoti di passare da una versione di Python all’altra globalmente o per cartella senza mai cambiare il codice dello script.

Ti consiglio di usare la nostra Conda Cheat Sheet quando vuoi dare un’occhiata rapida alla gestione dei pacchetti e al lavoro con l’ambiente conda.

Massimizzare la portabilità tra sistemi e ambienti

Per scrivere shebang portabili, segui queste best practice:

• Preferisci l’approccio basato sull’ambiente #!/usr/bin/env python3 ai percorsi assoluti dell’interprete.

• Mantieni lo shebang corto e semplice.

• Documenta chiaramente la versione di Python richiesta e le dipendenze.

• Usa la codifica UTF-8 ed evita assunzioni specifiche della piattaforma.

• Puoi sempre combinare shebang chiari con estensioni .py per la compatibilità multipiattaforma.

Evitare errori comuni e anti-pattern

Questi sono gli errori più comuni a cui prestare attenzione quando scrivi shebang portabili:

• Posiziona sempre lo shebang #! sulla prima riga, senza spazi tra #! e il percorso.

• Non superare i limiti di caratteri del sistema. Linux ha un limite di 127 byte e macOS di 256 byte.

• Sii cauto nella scelta tra percorsi assoluti e env, perché codificare percorsi dell’interprete può essere rischioso in ambienti sensibili.

Shebang in packaging e distribuzione

Quando impacchetti applicazioni Python, strumenti come pip, setuptools e pipx possono riscrivere le righe di shebang durante l’installazione per puntare all’interprete corretto. 

Ad esempio, quando esegui pip install your-package, l’installer genera automaticamente una riga di shebang che punta all’esatto interprete Python usato per l’installazione. Pertanto, dovresti sempre definire i tuoi entry point in setup.py o pyproject.toml invece di fare affidamento esclusivo su shebang manuali per le app distribuite.

Compatibilità con Windows e soluzioni alternative

Windows non supporta nativamente gli shebang a livello di sistema operativo. Tuttavia, il Python Launcher py.exe può leggere le righe di shebang e selezionare l’interprete appropriato. Anche se questo strumento è solitamente installato con Python su Windows, assicurati sempre di averlo installato prima di eseguire script con shebang.

Puoi anche eseguire gli script tramite Windows Subsystem for Linux (WSL) o fare affidamento sulle associazioni di file basate sul registro.

Restrizioni e limitazioni specifiche dell’ambiente

Sistemi operativi diversi trattano gli argomenti dello shebang in modo differente. Linux in genere tratta tutto ciò che segue il primo spazio come un unico argomento, mentre macOS/FreeBSD possono gestire più argomenti in modo diverso.

Come regola generale, non usare più di un argomento nello shebang e lascia che sia lo script a gestire il resto della configurazione di runtime complessa.

Problemi di codifica dei caratteri e terminatori di riga

Per garantire la coerenza, il file dovrebbe usare una codifica compatibile, di solito UTF-8 senza BOM, e lo shebang deve essere i primi byte del file.

È importante notare che Windows usa \r\n (CRLF) come terminatori di riga, mentre Unix usa \n (LF). Se salvi uno script su Windows con CRLF e provi a eseguirlo su Linux, il kernel penserà che il percorso dell’interprete sia python3\r, che non esiste. Per evitare questo problema, imposta sempre l’editor in modo che usi terminatori di riga LF (Unix) per gli script Python.

Approcci moderni allo shebang in Python

Lo sviluppo moderno in Python offre alternative allo scripting con shebang che semplificano esecuzione, packaging e distribuzione. I metodi seguenti riducono la gestione manuale dell’interprete e offrono una migliore compatibilità tra sistemi operativi diversi.

Console script ed entry point in setuptools

I console script sono una funzionalità di packaging che ti consente di definire comandi da riga di comando nella configurazione del progetto. Ad esempio, puoi definirli in setup.py o pyproject.toml. Questo ti permette di dichiarare un entry point che mappa un nome di comando a una funzione Python.

Quando il pacchetto viene installato, l’installer genera automaticamente un piccolo script di lancio adatto al sistema operativo. Questo script include il riferimento corretto all’interprete e gestisce l’esecuzione in modo trasparente.

Pertanto, gli entry point semplificano la distribuzione degli script eliminando la necessità di gestire manualmente gli shebang, assicurano l’uso dell’interprete Python corretto e forniscono un comportamento coerente tra piattaforme

L’approccio con il modulo __main__.py

Come visto prima, il file __main__.py ti consente di eseguire un intero pacchetto come programma usando la sintassi python -m package_name. Quando Python vede un pacchetto con un file __main__.py, tratta quel file come entry point del pacchetto.

Questo approccio ti permette di distribuire la tua app come file .zip o come "Python Zip Application" usando il modulo zipapp. Mantiene la logica di esecuzione centralizzata, evita di disseminare script eseguibili nel progetto e facilita il mantenimento di una struttura del pacchetto pulita.

PEP 723 e metadati inline degli script

La PEP 723 introduce un modo standardizzato per incorporare metadati inline direttamente negli script Python. Questi metadati possono descrivere dipendenze, requisiti di versione di Python e altri dettagli di esecuzione in un formato leggibile dalle macchine.

L’obiettivo della PEP 723 è rendere gli script standalone più facili da eseguire, condividere e gestire, soprattutto con strumenti moderni che possono leggere i metadati e configurare automaticamente l’ambiente richiesto.

Considerazioni speciali sullo shebang in Python

Di seguito trovi considerazioni avanzate rilevanti per tool distribuiti, sistemi condivisi e applicazioni multipiattaforma.

Sostituzione dello shebang da parte di sistemi di build e strumenti di installazione

Strumenti di build come setuptools, flit o poetry controllano i tuoi script durante il processo di installazione. Se uno script viene installato tramite pip, l’installer sostituisce il tuo generico #!/usr/bin/env python3 con il percorso assoluto dello specifico interprete Python usato per quell’installazione.

Questa riscrittura assicura che lo script sia "bloccato" all’ambiente in cui è stato installato, evitando che venga eseguito accidentalmente con una versione di Python diversa che potrebbe non avere le dipendenze richieste.

Uso di interpreti personalizzati e linguaggi specifici di dominio

Lo shebang non è limitato ai binari Python standard. Può puntare a qualsiasi eseguibile in grado di processare un file di testo. Se usi PyPy per le prestazioni o Jython per l’integrazione con Java, il tuo shebang lo rifletterà: #!/usr/bin/env pypy3.

Nel data science o nel DevOps, potresti vedere shebang che puntano a motori personalizzati che interpretano DSL (Domain Specific Language) simili a Python, permettendo di trattare il file come una configurazione o un file di task specializzato.

Ti consiglio di dare un’occhiata alla nostra Python for Data Science Cheat Sheet, che puoi scaricare, se cerchi una guida rapida per lavorare con Python e imparare più facilmente.

Considerazioni sulla sicurezza con gli shebang

In ambienti multiutente, gli shebang possono introdurre rischi di sicurezza se non gestiti con attenzione. Ad esempio, usare il percorso relativo #!/usr/bin/env si affida al PATH dell’utente, che potrebbe essere manipolato per puntare a un interprete malevolo.

Per ridurre tali rischi:

• Usa percorsi assoluti dell’interprete in contesti sensibili alla sicurezza.

• Limita i permessi di scrittura sugli script eseguibili.

• Evita di eseguire script da directory non affidabili.

• Rivedi la configurazione del PATH in ambienti con privilegi.

Impatto degli shebang sullo scripting multipiattaforma

Gli shebang funzionano nativamente sui sistemi Unix-like ma hanno supporto nativo limitato su Windows. Questa differenza può influire sulla portabilità quando gli script vengono condivisi tra sistemi operativi.

Per un comportamento coerente tra piattaforme:

• Combina shebang con entry point di packaging per gli strumenti CLI.

• Usa env per flessibilità.

• Usa il launcher py su Windows, che rispetta gli shebang in stile Unix.

Conclusione

Gli shebang svolgono un ruolo importante nel modo in cui vengono eseguiti gli script Python, facendo da ponte tra il tuo codice e il sistema operativo. Se usati correttamente, consentono l’esecuzione diretta, una selezione chiara dell’interprete e script più portabili e facili da usare.

Come passo successivo, prova a sperimentare flussi di lavoro di packaging, esplorare le PEP relative all’esecuzione degli script o contribuire a tool e documentazione condivisi. Approfondire la comprensione di come vengono eseguiti gli script Python ti aiuterà a scrivere codice più pulito e migliore.

Puoi saperne di più dai nostri percorsi di competenze Fondamenti di dati con Python e Fondamenti di programmazione in Python. Infine, personalmente consiglio il nostro percorso professionale Sviluppatore Python per imparare test del codice e controllo di versione nello scraping web e nello sviluppo di pacchetti.