Configurar o ambiente Python

Os jobs do PySpark no Serviço Gerenciado para Apache Spark são executados por um interpretador Python no cluster. O código do job precisa ser compatível no ambiente de execução com a versão e as dependências do interpretador Python.

Verificar a versão do interpretador e os módulos

O programa de amostra check_python_env.py a seguir verifica o usuário do Linux que executa o job, o interpretador do Python e os módulos disponíveis.

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))

Execute o programa:

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

Exemplo de resposta: 

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'])

Ambientes Python de imagem do Serviço Gerenciado para Apache Spark

As seções a seguir descrevem os ambientes Python para clusters compatíveis com a versão da imagem do Serviço Gerenciado para Apache Spark.

Versão 2.x da imagem do Serviço Gerenciado para Apache Spark

O Conda (ou micromamba em imagens 2.3) está instalado em clusters do Serviço Gerenciado para Apache Spark 2.x. O interpretador padrão do Python 3 está localizado na instância de VM em /opt/conda/default/bin. As páginas a seguir listam a versão do Python incluída nas versões de imagem 2.x compatíveis do Serviço Gerenciado para Apache Spark:

O interpretador Python não padrão do SO está disponível em /usr/bin/.

É possível instalar pacotes conda e pip no ambiente base ou configurar seu próprio ambiente conda no cluster usando propriedades do cluster relacionadas ao conda.

Observação sobre o canal conda: as versões de imagem padrão 2.1, 2.2 e 2.3 do Serviço Gerenciado para Apache Spark não incluem canais de pacotes conda pré-configurados (como defaults ou conda-forge) em .condarc. Consulte a nota da versão de 4 de setembro de 2026. Transmitir nomes de pacotes sem prefixo para dataproc:conda.packages ou executar conda install PACKAGE sem especificar um canal falha com CondaValueError: No channels available to install from ou PackagesNotFoundError.

Para mais informações, incluindo versões de imagem afetadas, solicitações de extensão e etapas de migração recomendadas, consulte Migrar e configurar canais do Conda.

Para instalar pacotes do Conda, especifique explicitamente o canal:

  • Ao usar a propriedade dataproc:conda.packages, use o formato CHANNEL::PACKAGE==VERSION (por exemplo, dataproc:conda.packages=conda-forge::pip==24.0).
  • Ao executar conda install na linha de comando, transmita a flag -c (ou --channel). Por exemplo, conda install PACKAGES -c conda-forge.

Exemplo:

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'

Versão 3.0 da imagem do Serviço Gerenciado para Apache Spark

O Python 3 está instalado nos clusters do Serviço Gerenciado para Apache Spark 3.0. Nas imagens 3.0, o Pixi é instalado como parte da instalação do Python e é usado para instalar pacotes Python em vez do Conda.

Evitar problemas de download de pacotes

Os nós de cluster do Serviço Gerenciado para Apache Spark baixam pacotes de repositórios públicos externos do Python ao instalar pacotes personalizados conda e pip (consulte propriedades do cluster relacionadas ao conda). Para evitar falhas na criação de clusters devido à indisponibilidade de repositórios públicos do Python, crie uma imagem personalizada do Serviço Gerenciado para Apache Spark ou faça upload das dependências para um bucket do Cloud Storage. Consulte Fazer o download de dependências com clusters somente de IP interno.

Escolher um interpretador Python para um job

Se vários interpretadores do Python estiverem instalados no cluster, o sistema vai executar /etc/profile.d/effective-python.sh, que exporta a variável de ambiente PYSPARK_PYTHON para escolher o interpretador padrão do Python para seus jobs do PySpark. Se você precisar de um interpretador Python não padrão para um job do PySpark, ao enviar o job para o cluster, defina as propriedades spark.pyspark.python e spark.pyspark.driver.python para o caminho ou a versão do Python necessários (por exemplo, "/usr/bin/python3" ou "python3.11").

Exemplo:

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 com sudo

Se você se conectar a um nó de cluster usando SSH, ao executar sudo python --version, a versão do Python mostrada poderá ser diferente da versão mostrada por python --version. Essa diferença de versão pode ocorrer porque o sudo usa o Python /usr/bin/python padrão do sistema e não executa /etc/profile.d/effective-python.sh para inicializar o ambiente Python. Para uma experiência consistente ao usar sudo, localize o caminho do Python definido em /etc/profile.d/effective-python.sh e execute o comando env para definir o PATH como esse caminho do Python. Por exemplo:

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

Usar propriedades de cluster relacionadas ao conda

É possível personalizar o ambiente conda durante a criação do cluster usando propriedades do cluster relacionadas ao conda.

Há duas maneiras mutuamente exclusivas de personalizar o ambiente do conda ao criar um cluster do Serviço Gerenciado para Apache Spark:

  1. Use a propriedade de cluster dataproc:conda.env.config.uri para criar e ativar um novo ambiente conda no cluster. ou

  2. Use as propriedades de cluster dataproc:conda.packages e dataproc:pip.packages para adicionar pacotes conda e pip, respectivamente, ao ambiente conda base no cluster.

Propriedades do cluster relacionadas ao conda

  • dataproc:conda.env.config.uri:o caminho absoluto para um arquivo de configuração YAML do ambiente conda localizado no Cloud Storage. Esse arquivo é usado para criar e ativar um novo ambiente conda no cluster. Como as imagens padrão não incluem canais Conda pré-configurados, verifique se o arquivo environment.yaml lista explicitamente os canais de pacote necessários (como conda-forge) em channels.

    Exemplo:

    1. Receba ou crie um arquivo de configuração environment.yaml do conda. É possível criar o arquivo manualmente, usar um arquivo existente ou exportar um ambiente conda para um arquivo environment.yaml usando o seguinte comando: 

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

    2. Copie o arquivo de configuração para o bucket do Cloud Storage. 

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

    3. Crie o cluster e aponte para o arquivo de configuração do ambiente no 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:uma lista de pacotes conda com canais e versões específicos a serem instalados no ambiente de base, formatada como CHANNEL::PACKAGE==VERSION (por exemplo, conda-forge::pkg1==v1,conda-forge::pkg2==v2...). Se conda não conseguir resolver conflitos com pacotes existentes no ambiente de base, os pacotes conflitantes não serão instalados.

    Observações:

    • Como as versões de imagem padrão do Serviço Gerenciado para Apache Spark 2.1, 2.2 e 2.3 não incluem canais conda pré-configurados em .condarc, é necessário adicionar um prefixo a cada nome de pacote com o canal dele (como conda-forge::). Se você transmitir nomes de pacotes sem prefixo, a ação vai falhar com CondaValueError: No channels available to install from ou PackagesNotFoundError.

    • As propriedades de cluster dataproc:conda.packages e dataproc:pip.packages não podem ser usadas com a propriedade de cluster dataproc:conda.env.config.uri.

    • Ao especificar vários pacotes (separados por vírgula), é necessário especificar um caractere delimitador alternativo (consulte a propriedade de cluster Formatação). O exemplo a seguir especifica "#" como o caractere delimitador para transmitir vários nomes de pacotes separados por vírgulas à propriedade dataproc:conda.packages.

    Exemplo:

    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:uma lista de pacotes pip com versões específicas a serem instaladas no ambiente de base, formatada como pkg1==v1,pkg2==v2.... O pip só faz upgrade das dependências atuais se necessário. Os conflitos podem tornar o ambiente inconsistente.

    Observações:

    • As propriedades de cluster dataproc:pip.packages e dataproc:conda.packages não podem ser usadas com a propriedade de cluster dataproc:conda.env.config.uri.

    • Ao especificar vários pacotes (separados por vírgula), é necessário especificar um caractere delimitador alternativo (consulte a propriedade de cluster Formatação). O exemplo a seguir especifica "#" como o caractere delimitador para transmitir vários nomes de pacotes separados por vírgulas para a propriedade dataproc:pip.packages.

    Exemplo:

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

  • É possível usar dataproc:conda.packages e dataproc:pip.packages ao criar um cluster.

    Exemplo:

    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 ...