Python 環境を構成する

Managed Service for Apache Spark の PySpark ジョブは、クラスタ上の Python インタープリタによって実行されます。ジョブコードは、実行時に Python インタープリタのバージョンおよび依存関係と互換性がなければなりません。

インタープリタのバージョンとモジュールを確認する

次の check_python_env.py サンプル プログラムは、ジョブを実行している Linux ユーザー、Python インタープリタ、使用可能なモジュールを確認します。

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

プログラムを実行します。

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

出力例:

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

Managed Service for Apache Spark イメージの Python 環境

以降のセクションでは、サポートされている Managed Service for Apache Spark イメージ バージョンのクラスタの Python 環境について説明します。

Managed Service for Apache Spark イメージ バージョン 2.x

Conda（または 2.3 イメージの micromamba）は、Managed Service for Apache Spark 2.x クラスタにインストールされます。デフォルトの Python 3 インタープリタは、VM インスタンスの /opt/conda/default/bin にあります。次のページには、サポートされている Managed Service for Apache Spark 2.x イメージ バージョンに含まれる Python バージョンが一覧表示されます。

• 2.1
• 2.2
• 2.3

OS のデフォルト以外の Python インタープリタは /usr/bin/ で使用できます。

conda パッケージと pip パッケージを base 環境にインストールするか、Conda 関連のクラスタ プロパティを使用して、クラスタに独自の conda 環境をセットアップできます。

Conda チャネルに関する注: デフォルトの Managed Service for Apache Spark 2.1、2.2、2.3 のイメージ バージョンには、.condarc に事前構成された Conda パッケージ チャネル（defaults や conda-forge など）が含まれていません（2026 年 9 月 4 日のリリースノートを参照）。接頭辞のないパッケージ名を dataproc:conda.packages に渡すか、チャネルを指定せずに conda install PACKAGE を実行すると、CondaValueError: No channels available to install from または PackagesNotFoundError で失敗します。

Conda パッケージをインストールするには、チャネルを明示的に指定する必要があります。

• dataproc:conda.packages プロパティを使用する場合は、CHANNEL::PACKAGE==VERSION 形式（dataproc:conda.packages=conda-forge::pip==24.0 など）を使用します。
• コマンドラインで conda install を実行するときに、-c（または --channel）フラグを渡します（例: conda install PACKAGES -c conda-forge）。

例:

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'

Managed Service for Apache Spark イメージ バージョン 3.0

Python 3 は、Managed Service for Apache Spark 3.0 クラスタにインストールされています。3.0 イメージでは、Pixi が Python のインストールの一部としてインストールされ、Conda の代わりに Python パッケージのインストールに使用されます。

パッケージのダウンロードに関する問題を回避する

Managed Service for Apache Spark クラスタノードは、conda と pip のカスタム パッケージをインストールするときに、外部の公開 Python リポジトリからパッケージをダウンロードします（conda 関連のクラスタ プロパティをご覧ください）。公開 Python リポジトリを使用できないためにクラスタの作成が失敗しないようにするには、Managed Service for Apache Spark カスタム イメージを作成するか、依存関係を Cloud Storage バケットにアップロードすることを検討してください（内部 IP のみのクラスタで依存関係をダウンロードするをご覧ください）。

ジョブの Python インタープリタを選択する

複数の Python インタープリタがクラスタにインストールされている場合、システムは /etc/profile.d/effective-python.sh を実行し、PYSPARK_PYTHON 環境変数をエクスポートして PySpark ジョブのデフォルトの Python インタープリタを選択します。PySpark ジョブにデフォルト以外の Python インタープリタが必要な場合は、ジョブをクラスタに送信するときに、spark.pyspark.python と spark.pyspark.driver.python プロパティを必要な Python パスまたはバージョン（「/usr/bin/python3」や「python3.11」など）に設定します。

例:

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"

sudo を使用した Python

SSH を使用してクラスタノードに接続する場合、sudo python --version を実行すると、表示される Python のバージョンが python --version で表示されるバージョンと異なる場合があります。このバージョンの違いが生じる場合は、sudo がデフォルトのシステム Python /usr/bin/python を使用しており、/etc/profile.d/effective-python.sh を実行して Python 環境を初期化していない可能性があります。sudo を使用する際の挙動に相違が出ないように、あらかじめ /etc/profile.d/effective-python.sh に設定された Python パスを確認してから、env コマンドを実行して PATH に同じ Python パスを設定します。次に例を示します。

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

conda 関連のクラスタ プロパティを使用する

conda 環境は、クラスタを作成するときに conda 関連のクラスタ プロパティを使用してカスタマイズできます。

Managed Service for Apache Spark クラスタの作成時に、Conda 環境をカスタマイズする方法は相互排他的に 2 つあります。

1. dataproc:conda.env.config.uri クラスタ プロパティを使用して、クラスタ上に新しい Conda 環境を作成して有効にします。または

2. dataproc:conda.packages クラスタ プロパティと dataproc:pip.packages クラスタ プロパティを使用して、クラスタ上の conda base 環境にそれぞれ conda パッケージと pip パッケージを追加します。

   警告: プロパティで指定された新しいパッケージや環境のインストールにかかる時間によっては、クラスタの作成がタイムアウトすることがあります。このタイムアウトは、10 分に設定されています。

conda 関連のクラスタ プロパティ

• dataproc:conda.env.config.uri: Cloud Storage にある Conda 環境 YAML 構成ファイルへの絶対パス。このファイルは、クラスタ上で新しい conda 環境を作成して有効にするために使用されます。デフォルトのイメージには事前構成された Conda チャネルが含まれていないため、environment.yaml ファイルの channels に必要なパッケージ チャネル（conda-forge など）が明示的にリストされていることを確認してください。

  注: dataproc:conda.env.config.uri クラスタ プロパティは、dataproc:conda.packages または dataproc:pip.packages クラスタ プロパティで使用できません。

  例:

  1. conda environment.yaml 構成ファイルを取得または作成します。ファイルを手動で作成するか、既存のファイルを使用するか、次のコマンドを使用して environment.yaml ファイルに既存の Conda 環境をエクスポートできます。

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

  2. 構成ファイルを Cloud Storage バケットにコピーします。

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

  3. 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: ベース環境にインストールされる特定のチャンネルとバージョンの conda パッケージのリスト。「CHANNEL::PACKAGE==VERSION」の形式です（conda-forge::pkg1==v1,conda-forge::pkg2==v2... など）。conda がベース環境にある既存パッケージとの競合の解決に失敗すると、競合するパッケージはインストールされません。

  注:

  • デフォルトの Managed Service for Apache Spark 2.1、2.2、2.3 イメージ バージョンには .condarc に事前構成済みの Conda チャネルが含まれていないため、各パッケージ名の前にチャネル（conda-forge:: など）を付ける必要があります。接頭辞のないパッケージ名を渡すと、CondaValueError: No channels available to install from または PackagesNotFoundError で失敗します。

  • dataproc:conda.packages と dataproc:pip.packages のクラスタ プロパティは、dataproc:conda.env.config.uri クラスタ プロパティと一緒に使用できません。

  • （カンマで区切られた）複数のパッケージを指定する場合は、別の区切り文字を指定する必要があります。クラスタ プロパティの書式設定をご覧ください。次の例では、複数のカンマ区切りのパッケージ名を dataproc:conda.packages プロパティに渡すための区切り文字として「#」を指定しています。

  例:

  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: ベース環境にインストールされる特定のバージョンの pip パッケージのリスト。「pkg1==v1,pkg2==v2...」の形式です。pip は、必要な場合にのみ既存の依存関係をアップグレードします。競合が発生すると、環境に不整合が生じる可能性があります。

  注:

  • dataproc:pip.packages と dataproc:conda.packages のクラスタ プロパティは、dataproc:conda.env.config.uri クラスタ プロパティと一緒に使用できません。

  • （カンマで区切られた）複数のパッケージを指定する場合は、別の区切り文字を指定する必要があります。クラスタ プロパティの書式設定をご覧ください。次の例では、複数のカンマ区切りのパッケージ名を dataproc:pip.packages プロパティに渡すための区切り文字として「#」を指定しています。

  例:

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

• dataproc:conda.packages と dataproc:pip.packages は、クラスタを作成するとき、一緒に使用できます。

  例:

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