Import circolare in Python: cause, soluzioni e best practice

Il sistema di import di Python è progettato per essere semplice e intuitivo. Nella maggior parte dei casi, puoi organizzare il codice in più file e riunire tutto usando semplici istruzioni import.

Tuttavia, quando i moduli iniziano a dipendere l’uno dall’altro, potresti imbatterti in un problema frustrante: l’import circolare. Questi errori spesso compaiono inaspettatamente, con messaggi confusi come:

ImportError: cannot import name 'X' from 'Y' (most likely due to a circular import)Offerto da

In questo articolo vedremo cosa sono gli import circolari, perché si verificano e come risolverli con strategie semplici ed efficaci. Vedremo anche come progettare il tuo codice per evitarli del tutto, rendendo i tuoi progetti più solidi, manutenibili e facili da capire.

Cos’è un import circolare in Python?

Un import circolare si verifica quando due o più moduli Python dipendono tra loro, direttamente o indirettamente. Quando Python prova a importarli, finisce intrappolato in un loop e non riesce a completare il processo di import.

Ecco un semplice esempio con due moduli:

# file: module_a.py
from module_b import func_b

def func_a():
    print("Function A")
    func_b()Offerto da

# file: module_b.py
from module_a import func_a

def func_b():
    print("Function B")
    func_a()Offerto da

Eseguendo uno qualsiasi di questi file otterrai il seguente errore:

ImportError: cannot import name 'func_a' from 'module_a' (most likely due to a circular import)Offerto da

Cosa succede qui? Python inizia caricando module_a, che importa module_b. Ma poi module_b prova a importare di nuovo module_a, prima che func_a sia stata definita. Dato che Python inizializza ciascun modulo una sola volta, finisce per lavorare con una versione parzialmente caricata di module_a e l’import fallisce.

Per capirlo meglio, immagina il flusso di import così:

Flusso di import circolare in Python. Immagine dell’autore. 

Questo crea un ciclo di dipendenze. Poiché Python non ricarica i moduli già in fase di import, incontra definizioni mancanti e genera un errore.

Messaggi di errore tipici

Ecco alcuni messaggi comuni che segnalano un problema di import circolare:

• ImportError: cannot import name 'X' from 'Y'

• AttributeError: partially initialized module 'X' has no attribute 'Y'

Questi errori possono essere particolarmente fuorvianti perché spesso compaiono in profondità nello stack delle chiamate, non alla riga di codice dove è iniziato il problema reale.

Perché si verificano gli import circolari

Gli import circolari di solito non sono intenzionali. Sono un effetto collaterale di come i moduli sono strutturati e di come funzioni, classi o costanti sono condivise tra loro. Capire le cause alla radice può aiutarti a correggere i problemi esistenti ed evitare di crearne di nuovi man mano che la tua base di codice cresce.

Cause comuni degli import circolari

Diversi pattern di progettazione e strutture di progetto possono creare accidentalmente dipendenze circolari. Ecco alcuni degli scenari più comuni:

Dipendenze reciproche tra moduli

Due moduli si importano a vicenda per accedere a funzionalità. Ad esempio, utils.py chiama una funzione in core.py e core.py importa anche qualcosa da utils.py. Nessuno dei due può caricarsi completamente senza l’altro.

Import a livello top che scattano troppo presto

Se una classe o una funzione è importata a livello top (cioè fuori da una funzione o metodo), viene eseguita non appena il modulo viene importato. Questo può creare problemi se quell’import a livello top innesca un riferimento circolare.

Classi che dipendono l’una dall’altra

È comune nella progettazione orientata agli oggetti che una classe abbia bisogno di un’altra. Per esempio, una classe User che usa una classe Profile e viceversa. Se entrambe sono in moduli separati e importate a livello top, si verificherà un import circolare.

Confini di modulo poco chiari

Con la crescita dei progetti, il codice può diventare strettamente accoppiato tra moduli. Se le responsabilità non sono chiaramente separate, è facile ritrovarsi in un groviglio di import interdipendenti.

Import impliciti da framework o plugin

A volte gli import circolari accadono tramite librerie esterne, soprattutto se usi framework con plugin o funzionalità di auto-discovery. Queste possono attivare import indiretti e causare problemi circolari più difficili da tracciare.

Esempio reale: physics.py ed entities/post.py

Supponiamo che tu stia costruendo un motore di gioco di base. Hai due moduli:

• physics.py gestisce gravità e logica di collisione.
• entities/post.py definisce le classi giocatore e nemico, che usano funzioni da physics.py.

Ecco come potrebbe apparire il codice:

# file: entities/post.py
from physics import apply_gravity  # Top-level import
class Player:
    def __init__(self, mass):
        self.mass = mass
    def update(self):
        apply_gravity(self)Offerto da

# file: physics.py
from entities.post import Player  # Top-level import creates circular dependency
def apply_gravity(entity):
    if isinstance(entity, Player):
        print(f"Applying gravity to player with mass {entity.mass}")Offerto da

Ora, se provi a importare Player o a eseguire la logica di gioco, otterrai il seguente errore:

Traceback (most recent call last):
  File "entities/post.py", line 1, in <module>
    from physics import apply_gravity
  File "physics.py", line 1, in <module>
    from entities.post import Player
ImportError: cannot import name 'Player' from 'entities.post' (most likely due to a circular import)Offerto da

Ecco cosa sta succedendo:

1. entities/post.py viene importato per primo e prova a caricare apply_gravity() da physics.py.

2. physics.py inizia a caricarsi e prova a importare la classe Player da entities/post.py.

3. Ma Player non è ancora stata definita, e Python sta ancora lavorando su entities/post.py!

Questo crea un loop circolare in cui ciascun file attende che l’altro finisca di caricarsi. Python finisce con un modulo parzialmente inizializzato e genera un ImportError.

Questo tipo di dipendenza circolare indiretta è comune in progetti più grandi dove la logica è suddivisa tra moduli. Per fortuna, come vedremo tra poco, esistono diversi modi per risolverla ed evitarla.

Problemi causati dagli import circolari

Gli import circolari non causano solo errori di import: possono influire sul codice in modi più difficili da rilevare. Dai messaggi di errore fuorvianti ai problemi architetturali a lungo termine, ecco cosa potresti incontrare se le dipendenze circolari non vengono tenute sotto controllo.

ImportError e AttributeError

L’effetto più immediato di un import circolare è un errore durante il caricamento del modulo. Di solito si presenta in due forme:

• ImportError: cannot import name 'X' from 'Y': Python prova ad accedere a un nome che non è ancora stato definito perché il modulo non ha finito di caricarsi.

• AttributeError: partially initialized module 'X' has no attribute 'Y': Python ha importato il modulo, ma la funzione o classe che stai cercando di usare non esiste ancora a causa del loop di import.

Questi errori sono frustranti perché spesso indicano il sintomo (ad es. una funzione mancante) invece della causa (l’import circolare).

Dipendenze difficili da debuggare

Gli import circolari spesso creano catene invisibili di dipendenze nel tuo codebase. Un bug in un modulo può sembrare originare in un altro, rendendo il debugging molto più difficile. Potresti passare del tempo a guardare il file sbagliato, senza sapere che il problema è causato da un riferimento circolare a diversi livelli di profondità.

Questo è particolarmente problematico nelle applicazioni grandi, dove un piccolo import in cima a un file può innescare una cascata di problemi.

Scarsa leggibilità e manutenibilità del codice

Gli import circolari sono di solito un segnale che i moduli fanno troppo o sono troppo strettamente accoppiati. Quando i file dipendono a catena l’uno dall’altro, diventa più difficile capire dove risiede la logica e come interagiscono le diverse parti del tuo codice.

Col tempo, questo rende il codice più difficile da mantenere. I nuovi membri del team (o tu in futuro) potrebbero dover dedicare tempo extra a districare la rete di interdipendenze prima di poter fare modifiche.

Potenziali colli di bottiglia nelle prestazioni

In alcuni casi, gli sviluppatori provano a “risolvere” gli import circolari con import dinamici o ripetuti usando tecniche come importlib o import locali dentro le funzioni. Anche se possono funzionare, possono introdurre piccole penalità di performance dovute a risoluzioni ripetute o caricamenti ritardati a runtime, soprattutto se usati spesso in cicli stretti o in applicazioni di grande scala.

Un campanello d’allarme architetturale

Soprattutto, gli import circolari segnalano spesso un problema di design più profondo. Suggeriscono una mancanza di chiara separazione delle responsabilità. Moduli che dipendono troppo l’uno dall’altro sono più difficili da testare, scalare e rifattorizzare. In altre parole, gli import circolari non sono solo bug: sono code smell.

Nella prossima sezione, vedremo come correggere gli import circolari usando strategie pratiche come import locali, refactoring e caricamento dinamico. Queste soluzioni non solo fermano gli errori, ma ti aiutano anche a ripulire l’architettura. Per riassumere gli effetti pratici degli import circolari e perché sono più di un semplice fastidio, ecco una rapida panoramica dei principali problemi che causano:

Riconoscere questi sintomi è il primo passo. Ora vediamo come risolvere gli import circolari con strategie che migliorano sia la funzionalità sia la struttura del codice.

Come risolvere gli import circolari

Una volta identificato un import circolare nel tuo codice, la buona notizia è che esistono diversi modi efficaci per risolverlo. Vediamo le tecniche più affidabili.

Rifattorizza i tuoi moduli

Spesso gli import circolari accadono perché i moduli fanno troppo o sono troppo connessi. Una delle soluzioni più pulite è riorganizzare il codice:

• Spostando la funzionalità condivisa in un terzo file (ad es. common.py, utils.py o base.py)

• Unendo due moduli interdipendenti in uno solo, se fanno logicamente parte della stessa unità.

Ecco un esempio di estrazione della logica condivisa:

# file: common.py
def apply_gravity(entity):
    print("Gravity applied to", entity)

# file: physics.py
from common import apply_gravity

# file: entities/post.py
from common import apply_gravityOfferto da

Spostando apply_gravity() in common.py, sia physics.py sia entities/post.py possono importarla senza dipendere l’uno dall’altro.

Usa import locali o lazy

Invece di importare in cima al file, inserisci l’import dentro la funzione o il metodo che lo usa davvero. Questo ritarda l’import finché la funzione non viene chiamata, dopo che tutti i moduli hanno finito di caricarsi. Ecco un esempio di lazy import dentro un metodo:

# file: physics.py
def apply_gravity(entity):
    from entities.post import Player  # Local import
    if isinstance(entity, Player):
        print("Applying gravity")Offerto da

Funziona bene quando l’import serve solo in situazioni specifiche. Assicurati solo di aggiungere un commento che spieghi perché l’import è lì.

Usa "import module" invece di "from module import …"

Usare import module rinvia la risoluzione dei nomi al runtime, il che può aiutare a evitare lookup anticipati che innescano import circolari.Il codice qui sotto è un esempio di import diretto che causa una risoluzione anticipata:

from physics import apply_gravity  # May cause a circular importOfferto da

Un approccio più adatto è usare l’accesso differito all’attributo:

import physics
def update():
    physics.apply_gravity()Offerto da

Questo metodo è semplice ed efficace in molti casi, specialmente quando devi accedere a una funzione o classe solo occasionalmente.

Sposta gli import in fondo

In alcuni scenari, semplicemente mettendo l’istruzione di import in fondo al file, dopo le definizioni di classi/funzioni, puoi risolvere il problema. Ecco un buon esempio:

# file: module_a.py
def func_a():
    print("Function A")
from module_b import func_b  # Import after definitionsOfferto da

Funziona solo se il nome importato non è richiesto durante l’inizializzazione del modulo, quindi usalo con attenzione.

Usa importlib per import dinamici

Il modulo integrato importlib di Python ti consente di caricare moduli in modo programmatico. È particolarmente utile per plugin opzionali o logica a runtime dove gli import vanno rimandati.

Ecco un esempio con importlib.import_module

import importlib
def get_player_class():
    entities = importlib.import_module("entities.post")
    return entities.PlayerOfferto da

Questo metodo evita del tutto gli import a livello top e mantiene le dipendenze flessibili. È un’ottima scelta per sistemi a plugin, estensioni o logiche di routing dinamiche.

Con diverse strategie tra cui scegliere, è utile confrontarle fianco a fianco. Ecco un rapido riferimento per aiutarti a decidere quale soluzione si adatta meglio alla tua situazione:

Come prevenire gli import circolari

Correggere gli import circolari è utile, ma evitarli del tutto è ancora meglio. Un codebase ben organizzato, con confini tra moduli chiaramente definiti, è molto meno soggetto a questi problemi.

Ecco alcuni modi comprovati per evitare import circolari nei progetti Python.

Pianifica presto l’architettura dei moduli

Gli import circolari spesso derivano da una struttura di progetto scadente. Evitali pianificando la disposizione dei moduli prima di buttarti nell’implementazione. Ecco alcune domande da porti:

• Ogni modulo ha una responsabilità singola e chiara?
• Stai separando la logica per ambito (ad es. modelli, servizi, utility)?
• Alcuni moduli possono essere combinati o astratti?

Usa un approccio top-down o uno strumento visivo per abbozzare come i moduli dovrebbero interagire prima di iniziare a scrivere codice.

Applica pattern architetturali

Pattern come model-view-controller (MVC) o architettura a livelli prevengono naturalmente gli import circolari imponendo una gerarchia di dipendenze.

• I controller possono dipendere dai modelli, ma non viceversa.
• Le view dipendono dai controller, ma non importano direttamente la business logic.

Questo flusso top-down mantiene le dipendenze pulite e unidirezionali.

Evita di importare dettagli di implementazione

Cerca di importare solo ciò che un modulo espone pubblicamente, non i suoi helper o classi interni. Per esempio, invece di importare una classe annidata in profondità in un altro modulo, esponi un’API pulita al livello superiore di quel modulo.

# Good
from auth import authenticate_user  # Clean interface

# Risky
from auth.utils.token_handler import generate_token  # Fragile and tightly coupledOfferto da

Questa pratica rende i moduli più facili da rifattorizzare senza creare dipendenze nascoste.

Fai attenzione con gli import relativi

Sebbene gli import relativi (from .module import X) possano rendere il codice più pulito, possono anche aumentare la probabilità di riferimenti circolari in package molto annidati.

Usali con parsimonia e solo quando migliorano chiaramente la leggibilità. Nelle applicazioni grandi, preferisci import assoluti con percorsi di modulo ben definiti.

Usa la dependency injection

Se due moduli si affidano a funzionalità condivise, valuta di iniettare la dipendenza invece di importarla. Ecco un esempio:

# Instead of importing directly
def run_simulation():
    from physics import apply_gravity
    apply_gravity()

# Use dependency injection
def run_simulation(apply_gravity_fn):
    apply_gravity_fn()Offerto da

Questo mantiene i moduli debolmente accoppiati e rende anche più facile il unit testing.

Visualizza il grafo degli import

Usa strumenti per ispezionare e visualizzare come i moduli dipendono tra loro:

• pydeps: genera grafi di dipendenza del tuo progetto.

• snakeviz: visualizza il profiling a runtime (utile se i lazy import influenzano le performance).

• pipdeptree: ispeziona le dipendenze dei pacchetti di terze parti.

Una revisione periodica di questi grafi può aiutare a intercettare import circolari prima che causino veri problemi.

Usa le code review come rete di sicurezza

Infine, rendi la struttura degli import parte della checklist di code review. Intercettare per tempo i problemi architetturali è molto più semplice che debuggare import rotti in seguito. Un rapido sguardo all’albero degli import può risparmiarti ore di frustrazione.

Conclusione

Gli import circolari sono una di quelle trappole di Python che all’inizio sembrano misteriose, ma una volta capito cosa succede “dietro le quinte” diventano molto più semplici da diagnosticare e risolvere.

In sostanza, gli import circolari sono un effetto collaterale di come sono strutturati i moduli e di come interagiscono. Tendono a comparire nei progetti in crescita, quando la logica diventa troppo accoppiata o le responsabilità si confondono tra i file. Ma sono anche un segnale utile, un’opportunità per fare un passo indietro, rivalutare l’architettura e semplificare il codebase.

Se vuoi affinare ulteriormente le tue competenze Python, dai un’occhiata a Writing Efficient Python Code per saperne di più sulla progettazione di codice manutenibile. Puoi anche costruire solide basi con il nostro corso Introduction to Python, oppure approfondire il design modulare con Object-Oriented Programming in Python: sono tutte ottime opzioni.