Python ModuleNotFoundError: No module named '...' - Soluzione

Soluzione Rapida

L’errore indica che Python non riesce a trovare il modulo specificato nel suo percorso di ricerca (sys.path).

  1. Installa il pacchetto nell’ambiente corretto: Usa python -m pip per assicurarti di installare il pacchetto per l’interprete Python corrente.

    # Windows
python -m pip install nome_pacchetto

# Linux / macOS
python3 -m pip install nome_pacchetto

  2. Verifica l’ambiente virtuale: Se usi un virtual environment (venv, conda, pipenv), attivalo prima di eseguire lo script.

    # Windows (Command Prompt)
.\venv\Scripts\activate

# Linux / macOS
source venv/bin/activate

  3. Controlla i pacchetti installati:

    # Verifica se il pacchetto è presente nella lista
python -m pip list

Perché accade questo errore

Python solleva ModuleNotFoundError (una sottoclasse di ImportError) quando l’istruzione import fallisce. Le cause principali sono:

  1. Pacchetto mancante: Non hai installato la libreria (pip install pandas).
  2. Ambiente errato: Hai installato il pacchetto globalmente, ma stai eseguendo lo script in un ambiente virtuale isolato (o viceversa).
  3. Typo nel nome: Hai scritto import Pands invece di import pandas.
  4. Shadowing del modulo: Hai chiamato il tuo script email.py, random.py o pandas.py, nascondendo il modulo standard o di terze parti.
  5. Struttura del progetto: Stai cercando di importare un modulo locale che non si trova nel PYTHONPATH.

Spiegazione Dettagliata

Quando esegui import my_module, l’interprete Python cerca il modulo in un ordine specifico definito in sys.path:

  1. Directory corrente: La cartella contenente lo script in esecuzione.
  2. PYTHONPATH: Directory aggiunte tramite la variabile d’ambiente.
  3. Libreria Standard: I moduli built-in di Python (es. os, sys).
  4. Site-packages: La cartella dove pip installa le librerie di terze parti.

Se Python scansiona tutte queste posizioni senza trovare my_module.py o una cartella my_module (con __init__.py), solleva l’errore.

Debugging di sys.path

Per capire dove Python sta cercando, aggiungi queste righe all’inizio del tuo script, prima dell’import che fallisce:

import sys
print("Eseguibile Python:", sys.executable)
print("Percorsi di ricerca:")
for path in sys.path:
    print(path)

# L'import che causa l'errore
import modulo_mancante

Se il percorso della tua libreria non appare nell’output, Python non potrà importarla.

Soluzione su Windows

Su Windows, è comune avere più versioni di Python installate (es. da Microsoft Store, Anaconda, installer ufficiale).

1. Usa il Python Launcher (py)

Il comando py gestisce automaticamente le versioni. Usa sempre il flag -m per legare pip all’interprete specifico.

# Installa per l'ultima versione di Python installata
py -m pip install requests

# Esegui lo script con lo stesso interprete
py script.py

2. Controlla il PATH

Se esegui pip direttamente, potresti usare un pip associato a un’altra installazione Python. Verifica con:

where pip
where python

Soluzione su Linux / macOS

I sistemi Unix spesso preinstallano Python (spesso Python 2 o una versione di sistema di Python 3).

1. Usa python3 esplicitamente

Evita python generico se non sei sicuro a cosa punti.

# Installa usando pip3
python3 -m pip install numpy

# Esegui con python3
python3 script.py

2. Permessi e User Install

Se ricevi errori di permesso (“Permission denied”), non usare sudo pip (potrebbe rompere i pacchetti di sistema). Usa --user:

python3 -m pip install --user numpy

Oppure, meglio ancora, usa sempre un ambiente virtuale.

Fix in Docker

Se l’errore appare durante la build o l’esecuzione di un container Docker:

  1. Manca l’installazione nel Dockerfile: Assicurati di eseguire pip install dopo aver copiato il file dei requisiti.

    COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]

  2. Multi-stage builds: Se usi build multi-stage, ricorda che i pacchetti installati in uno stage non vengono copiati automaticamente nel successivo. Devi copiare la cartella site-packages o reinstallare.

Common Variations

FAQ

Q: Ho installato il pacchetto, ma VS Code continua a sottolineare l’import in rosso. A: VS Code potrebbe usare un interprete diverso da quello del terminale. Clicca sulla versione di Python nella barra di stato in basso a destra (o premi Ctrl+Shift+P e cerca “Python: Select Interpreter”) e seleziona l’ambiente dove hai installato il pacchetto.

Q: “Requirement already satisfied” ma l’errore persiste. A: Il pacchetto è installato in un altro ambiente Python. Esegui which python (Linux/macOS) o where python (Windows) nel terminale dove esegui lo script e confrontalo con l’output di sys.executable nello script. Devono coincidere.

Q: Come importo un file dalla cartella superiore? A: Python non guarda automaticamente nelle cartelle superiori. Puoi modificare sys.path runtime (sconsigliato per produzione) o installare il tuo progetto in modalità modificabile (pip install -e .) se ha una struttura a pacchetto con setup.py o pyproject.toml. Soluzione rapida (hack):

import sys
import os
sys.path.append(os.path.abspath(".."))
import modulo_parent

Q: Perché non riesco a importare i miei file locali? A: Assicurati che la directory contenente i moduli abbia un file __init__.py (per Python < 3.3, ma buona prassi anche ora) e che tu stia eseguendo lo script dalla directory radice del progetto, oppure imposta la variabile d’ambiente PYTHONPATH=..

Q: L’errore appare solo in Jupyter Notebook. A: Il kernel di Jupyter potrebbe essere diverso dall’ambiente dove hai lanciato pip. Installa il pacchetto direttamente in una cella del notebook:

import sys
!{sys.executable} -m pip install nome_pacchetto