Librerie Python con ambito notebook

Le librerie con ambito notebook consentono di creare, modificare, salvare, riutilizzare e condividere ambienti Python personalizzati specifici di un notebook. Quando si installa una libreria con ambito notebook, solo il notebook corrente e tutti i processi associati a tale notebook hanno accesso a tale libreria. L'operazione non incide sugli altri notebook collegati allo stesso cluster.

Le librerie con ambito notebook non vengono mantenute tra le sessioni. È necessario reinstallare le librerie con ambito notebook all'inizio di ogni sessione o ogni volta che il notebook viene scollegato da un cluster.

Databricks consiglia di utilizzare il comando magic %pip per installare librerie Python limitate al notebook. Nei notebook serverless che eseguono l'ambiente versione 5 o successiva, è anche possibile usare %uv pip per installazioni più veloci.

È possibile usare %pip nei notebook pianificati come job. Se è necessario gestire l'ambiente Python in un notebook Scala, SQL o R, usare il %python comando magic insieme a %pip.

Potresti riscontrare un traffico maggiore sul nodo driver quando lavori con installazioni di librerie a livello di notebook. Vedi Raccomandazioni sulle dimensioni del nodo driver.

Per installare librerie per tutti i notebook collegati a un cluster, usare le librerie cluster. Vedere Librerie con ambito di calcolo.

Per una panoramica completa delle opzioni disponibili per l'installazione delle librerie Python in Databricks, vedere Gestione dell'ambiente Python.

Gestisci le librerie con %pip comandi

Il %pip comando è equivalente al comando pip e supporta la stessa API. Le sezioni seguenti illustrano esempi di come è possibile usare %pip i comandi per gestire l'ambiente. Per altre informazioni sull'installazione di pacchetti Python con pip, vedere la documentazione sull'installazione pip e le pagine correlate.

Installazioni più veloci con %uv pip

Il %uv pip comando magic è un'alternativa più veloce a %pip. %uv pip è alimentato dalla gestione pacchetti UV e condivide lo stesso ambiente virtuale notebook di %pip, in modo che i pacchetti installati con uno strumento siano visibili all'altro.

%uv pip è più veloce di %pip per le installazioni e le operazioni di sola lettura come list. Questo lo rende particolarmente adatto all'iterazione a partire da una specifica dell'ambiente.

%uv pipsupporta i sottocomandi standardpip: install, uninstall, list, showfreeze, check, e tree.

%uv pip install simplejson

%uv pip list

Altri modelli di installazione in questa pagina (volumi, file dell'area di lavoro, file dei requisiti, controllo della versione, repository privati) funzionano con %uv pip. È possibile sostituire %pip con %uv pip in uno di questi esempi.

%uv pip Limitazioni

• %uv pip uninstall non può rimuovere completamente le librerie preinstallate nell'ambiente serverless. Vengono rimossi solo i metadati del pacchetto. I file sottostanti rimangono nel file system e il pacchetto è ancora importabile.
• %uv pip non verifica la presenza di conflitti di dipendenza rispetto alle librerie preinstallate.
• Dopo l'esecuzione %uv pip dei comandi, il pannello laterale Ambiente del notebook potrebbe visualizzare alcune librerie preinstallate durante l'installazione dell'utente. Si tratta di un problema di visualizzazione e non influisce sulla funzionalità del pacchetto.
• %uv pip è destinato a un'iterazione interattiva veloce. Per configurare un ambiente riproducibile per il notebook, aggiungere dipendenze nel pannello laterale Ambiente del notebook.

Installare una libreria con %pip

%pip install matplotlib

Installa un pacchetto wheel di Python con %pip

%pip install /path/to/my_package.whl

Disinstallare una libreria con %pip

%pip uninstall -y matplotlib

L'opzione -y è obbligatoria.

Installare una libreria da un sistema di controllo della versione con %pip

%pip install git+https://github.com/databricks/databricks-cli

È possibile aggiungere parametri all'URL per specificare elementi come la versione o la sottodirectory Git. Per altre informazioni e per esempi sull'uso di altri sistemi di controllo della versione, vedere il supporto di VCS.

Installare un pacchetto privato con credenziali gestite dai segreti di Databricks con %pip

pip supporta l'installazione di pacchetti da origini private con autenticazione di base, includendo i sistemi di controllo delle versioni private e i repository di pacchetti privati, come ad esempio Nexus e Artifactory. La gestione dei segreti è disponibile tramite l'API Dei segreti di Databricks, che consente di archiviare token di autenticazione e password. Usare l'API DBUtils per accedere ai segreti dal notebook. Si noti che è possibile usare $variables nei comandi magic.

Per installare un pacchetto da un repository privato, specificare l'URL del repository con l'opzione --index-url%pip install o aggiungerlo al pip file di configurazione in ~/.pip/pip.conf.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install --index-url https://<user>:$token@<your-package-repository>.com/<path/to/repo> <package>==<version> --extra-index-url https://pypi.org/simple/

Allo stesso modo, è possibile utilizzare la gestione dei segreti con i comandi magici per installare pacchetti privati dai sistemi di controllo delle versioni.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

Installare un pacchetto da DBFS con %pip

È possibile usare %pip per installare un pacchetto privato salvato in DBFS.

Quando si carica un file in DBFS, il file viene rinominato automaticamente, sostituendo spazi, punti e trattini con caratteri di sottolineatura. Per i file wheel di Python, pip richiede che il nome del file usi i punti nel numero di versione (ad esempio, 0.1.0) e i trattini anziché spazi o caratteri di sottolineatura, quindi questi nomi dei file non vengono modificati.

%pip install /dbfs/mypackage-0.0.1-py3-none-any.whl

Installare un pacchetto da un volume con %pip

Con Databricks Runtime 13.3 LTS e versioni successive, è possibile usare %pip per installare un pacchetto privato salvato in un volume.

Quando si carica un file in un volume, il file viene rinominato automaticamente, sostituendo spazi, punti e trattini con caratteri di sottolineatura. Per i file wheel di Python, pip richiede che il nome del file utilizzi dei punti nella versione (ad esempio, 0.1.0) e dei trattini al posto di spazi o underscore, quindi questi nomi di file non vengono modificati.

%pip install /Volumes/<catalog>/<schema>/<path-to-library>/mypackage-0.0.1-py3-none-any.whl

Installare un pacchetto archiviato come file dell'area di lavoro con %pip

Con Databricks Runtime 11.3 LTS e versioni successive, è possibile usare %pip per installare un pacchetto privato salvato come file dell'area di lavoro.

%pip install /Workspace/<path-to-whl-file>/mypackage-0.0.1-py3-none-any.whl

Salva le librerie in un file dei requisiti

%pip freeze > /Workspace/shared/prod_requirements.txt

Tutte le sottodirectory nel percorso del file devono già esistere. Se si esegue %pip freeze > /Workspace/<new-directory>/requirements.txt, il comando non riesce se la directory /Workspace/<new-directory> non esiste già.

Usare un file dei requisiti per installare le librerie

Un file dei requisiti contiene un elenco di pacchetti da installare tramite pip. Un esempio di utilizzo di un file di requisiti è:

%pip install -r /Workspace/shared/prod_requirements.txt

Per ulteriori informazioni sui file requirements.txt, vedere formato del file dei requisiti.

Raccomandazioni sulle dimensioni del nodo driver

L'uso di librerie con ambito notebook potrebbe comportare un maggior traffico verso il nodo driver perché funziona per mantenere coerente l'ambiente tra i nodi executor.

Quando si usa un cluster con 10 o più nodi, Databricks consiglia queste specifiche come requisito minimo per il nodo driver:

• Per un cluster CPU a 100 nodi, usare Standard_D8ds_v5.
• Per un cluster GPU a 10 nodi, usare Standard_NC12.

Per i cluster di dimensioni maggiori, usare un nodo driver più grande.

Differenze tra %pip, %sh pipe !pip

%sh e ! eseguono un comando shell in un notebook; il primo è un comando magic ausiliario di Databricks, mentre il secondo è una funzionalità di IPython. pip è una sintassi abbreviata per %pip quando automagic è abilitato, ovvero l'impostazione predefinita nei notebook Python di Azure Databricks.

In Databricks Runtime 11.3 LTS e versioni successive, %pip, %sh pipe !pip tutte installano una libreria come libreria Python con ambito notebook. In Databricks Runtime 10.4 LTS e versioni precedenti, Databricks consiglia di usare solo %pip o pip per installare librerie a livello di notebook. Il comportamento di %sh pip e !pip non è coerente in Databricks Runtime 10.4 LTS e versioni successive.

Problemi noti

• In Databricks Runtime 9.1 LTS le librerie con ambito notebook non sono compatibili con i processi di streaming batch. Databricks consiglia invece di utilizzare le librerie del cluster o il kernel IPython.