Configura el entorno de Python

Un intérprete de Python en el clúster ejecuta los trabajos de PySpark en Managed Service para Apache Spark. El código del trabajo debe ser compatible en el tiempo de ejecución con la versión y las dependencias del intérprete de Python.

Verifica la versión y los módulos del intérprete

El siguiente programa de ejemplo check_python_env.py verifica que el usuario de Linux ejecute el trabajo, el intérprete de Python y los módulos disponibles.

import getpass
import importlib.util
import sys

print(f'This job is running as "{getpass.getuser()}".')
print(sys.executable, sys.version_info)
for package in sys.argv[1:]:
  print(importlib.util.find_spec(package))

Ejecuta el programa:

REGION=region
gcloud dataproc jobs submit pyspark check_python_env.py \
    --cluster=my-cluster \
    --region=${REGION} \
    -- pandas scipy

Resultado de muestra: 

This job is running as "root".
/opt/conda/default/bin/python sys.version_info(major=3, minor=11, micro=8, releaselevel='final', serial=0)
ModuleSpec(name='pandas', loader=<_frozen_importlibexternal.SourceFileLoader object at 0x7f8b9c0a3d90>, origin='/opt/conda/default/lib/python3.11/site-packages/pandas/init_.py', submodule_search_locations=['/opt/conda/default/lib/python3.11/site-packages/pandas'])
ModuleSpec(name='scipy', loader=<_frozen_importlibexternal.SourceFileLoader object at 0x7f8b9c0a3e50>, origin='/opt/conda/default/lib/python3.11/site-packages/scipy/init_.py', submodule_search_locations=['/opt/conda/default/lib/python3.11/site-packages/scipy'])

Imágenes de Managed Service para Apache Spark con entornos de Python

En las siguientes secciones, se describen los entornos de Python para los clústeres de versiones de imágenes compatibles de Managed Service para Apache Spark.

Versión 2.x de la imagen de Managed Service para Apache Spark

Conda (o micromamba en imágenes 2.3) está instalado en los clústeres de Managed Service para Apache Spark 2.x. El intérprete de Python 3 predeterminado se encuentra en la instancia de VM en /opt/conda/default/bin. En las siguientes páginas, se indica la versión de Python incluida en las versiones de imagen 2.x compatibles de Managed Service para Apache Spark:

El intérprete de Python no predeterminado del SO está disponible en /usr/bin/.

Puedes instalar paquetes de conda y pip en el entorno base o configurar tu propio entorno de conda en el clúster con propiedades del clúster relacionadas con Conda.

Nota sobre el canal de Conda: Las versiones de imagen predeterminadas 2.1, 2.2 y 2.3 de Managed Service para Apache Spark no incluyen canales de paquetes de Conda preconfigurados (como defaults o conda-forge) en .condarc (consulta la nota de la versión del 4 de septiembre de 2026). Si pasas nombres de paquetes sin prefijo a dataproc:conda.packages o ejecutas conda install PACKAGE sin especificar un canal, se producirá un error con CondaValueError: No channels available to install from o PackagesNotFoundError.

Para instalar paquetes de Conda, debes especificar el canal de forma explícita:

  • Cuando uses la propiedad dataproc:conda.packages, usa el formato CHANNEL::PACKAGE==VERSION (por ejemplo, dataproc:conda.packages=conda-forge::pip==24.0).
  • Cuando ejecutes conda install en la línea de comandos, pasa la marca -c (o --channel) (por ejemplo, conda install PACKAGES -c conda-forge).

Ejemplo:

REGION=region
gcloud dataproc clusters create my-cluster \
    --image-version=2.3 \
    --region=${REGION} \
    --properties=^#^dataproc:conda.packages='conda-forge::pytorch==2.1.0,conda-forge::coverage==6.5.0'#dataproc:pip.packages='tokenizers==0.15.0,datasets==2.16.1'

Versión 3.0 de la imagen de Managed Service para Apache Spark

Python 3 está instalado en los clústeres de Managed Service para Apache Spark 3.0. En las imágenes 3.0, Pixi se instala como parte de la instalación de Python y se usa para instalar paquetes de Python en lugar de Conda.

Evita problemas con la descarga de paquetes

Los nodos del clúster de Managed Service para Apache Spark descargan paquetes de repositorios externos públicos de Python cuando se instalan paquetes personalizados de conda y pip (consulta las propiedades del clúster relacionadas con conda). Para evitar errores en la creación de clústeres debido a la falta de disponibilidad de repositorios públicos de Python, considera crear una imagen personalizada de Managed Service para Apache Spark o subir las dependencias a un bucket de Cloud Storage (consulta Descarga dependencias con clústeres que solo tienen IP internas).

Elige un intérprete de Python para un trabajo

Si hay varios intérpretes de Python instalados en tu clúster, el sistema ejecuta /etc/profile.d/effective-python.sh, que exporta la variable de entorno PYSPARK_PYTHON para elegir el intérprete de Python predeterminado para tus trabajos de PySpark. Si necesitas un intérprete de Python no predeterminado para un trabajo de PySpark, cuando envíes el trabajo a tu clúster, configura las propiedades spark.pyspark.python y spark.pyspark.driver.python en la ruta de acceso o la versión de Python requeridas (por ejemplo, "/usr/bin/python3" o "python3.11").

Ejemplo:

REGION=region
gcloud dataproc jobs submit pyspark check_python_env.py \
    --cluster=my-cluster \
    --region=${REGION} \
    --properties="spark.pyspark.python=/usr/bin/python3,spark.pyspark.driver.python=/usr/bin/python3"

Python con sudo

Si te conectas a un nodo del clúster con SSH, cuando ejecutes sudo python --version, la versión de Python que se muestre puede ser diferente de la que muestra python --version. Esta diferencia de versión puede ocurrir porque sudo usa el /usr/bin/python de Python del sistema predeterminado y no ejecuta /etc/profile.d/effective-python.sh para inicializar el entorno de Python. Para una experiencia coherente cuando uses sudo, ubica la ruta de Python establecida en /etc/profile.d/effective-python.sh y, luego, ejecuta el comando env para establecer PATH en esta ruta de Python. Por ejemplo:

sudo env PATH=/opt/conda/default/bin:${PATH} python --version

Usa propiedades del clúster relacionadas con Conda

Puedes personalizar el entorno de conda durante la creación del clúster con propiedades del clúster relacionadas con Conda.

Hay dos formas mutuamente excluyentes de personalizar el entorno de Conda cuando creas un clúster de Managed Service para Apache Spark:

  1. Usa la propiedad del clúster dataproc:conda.env.config.uri para crear y activar un nuevo entorno de conda en el clúster. o

  2. Usa las propiedades del clúster dataproc:conda.packages y dataproc:pip.packages para agregar paquetes conda y pip, respectivamente, al entorno conda base en el clúster.

Propiedades del clúster relacionadas con Conda

  • dataproc:conda.env.config.uri: Es la ruta de acceso absoluta a un archivo de configuración YAML del entorno de conda ubicado en Cloud Storage. Este archivo se usa para crear y activar un nuevo entorno conda en el clúster. Dado que las imágenes predeterminadas no incluyen canales de Conda preconfigurados, asegúrate de que tu archivo environment.yaml enumere explícitamente los canales de paquetes requeridos (como conda-forge) en channels.

    Ejemplo:

    1. Obtén o crea un archivo de configuración environment.yaml de Conda. Puedes crear el archivo de forma manual, usar un archivo existente o exportar un entorno de Conda existente a un archivo environment.yaml con el siguiente comando: 

      conda env export --name=env-name > environment.yaml

    2. Copia el archivo de configuración en tu bucket de Cloud Storage. 

      gcloud storage cp environment.yaml gs://bucket-name/environment.yaml

    3. Crea el clúster y apunta el archivo de configuración de entorno en Cloud Storage. 

      REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --properties='dataproc:conda.env.config.uri=gs://bucket-name/environment.yaml' \
    ... other flags ...

  • dataproc:conda.packages: Una lista de paquetes conda con canales y versiones específicos que se instalarán en el entorno base, con el formato CHANNEL::PACKAGE==VERSION (por ejemplo, conda-forge::pkg1==v1,conda-forge::pkg2==v2...). Si conda no puede resolver conflictos con los paquetes existentes en el entorno base, no se instalarán los paquetes en conflicto.

    Notas:

    • Debido a que las versiones de imagen predeterminadas de Managed Service para Apache Spark 2.1, 2.2 y 2.3 no incluyen canales de Conda preconfigurados en .condarc, debes agregar el prefijo de cada nombre de paquete con su canal (como conda-forge::). Si pasas nombres de paquetes sin prefijo, se producirá un error con CondaValueError: No channels available to install from o PackagesNotFoundError.

    • Las propiedades del clúster dataproc:conda.packages y dataproc:pip.packages no se pueden usar con la propiedad del clúster dataproc:conda.env.config.uri.

    • Cuando especifiques varios paquetes (separados por una coma), debes especificar un carácter delimitador alternativo (consulta la propiedad del clúster Formato). En el siguiente ejemplo, se especifica "#" como el carácter delimitador para pasar varios nombres de paquetes separados por comas a la propiedad dataproc:conda.packages.

    Ejemplo:

    REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --properties='^#^dataproc:conda.packages=conda-forge::pytorch==2.1.0,conda-forge::coverage==6.5.0' \
    ... other flags ...

  • dataproc:pip.packages: Es una lista de paquetes pip con versiones específicas que se instalarán en el entorno base, con el formato pkg1==v1,pkg2==v2.... pip actualiza las dependencias existentes solo si es necesario. Los conflictos pueden hacer que el entorno sea incoherente.

    Notas:

    • Las propiedades del clúster dataproc:pip.packages y dataproc:conda.packages no se pueden usar con la propiedad del clúster dataproc:conda.env.config.uri.

    • Cuando especificas varios paquetes (separados por una coma), debes especificar un carácter delimitador alternativo (consulta la propiedad de clúster Formato). En el siguiente ejemplo, se especifica “#” como carácter delimitador para pasar varios nombres de paquetes separados por comas a la propiedad dataproc:pip.packages.

    Ejemplo:

    REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --properties='^#^dataproc:pip.packages=tokenizers==0.15.0,datasets==2.16.1' \
    ... other flags ...

  • Puedes usar dataproc:conda.packages y dataproc:pip.packages cuando crees un clúster.

    Ejemplo:

    REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --image-version=2.3 \
    --properties=^#^dataproc:conda.packages='conda-forge::pytorch==2.1.0,conda-forge::coverage==6.5.0'#dataproc:pip.packages='tokenizers==0.15.0,datasets==2.16.1' \
    ... other flags ...