Flink Python 任务支持使用 Python 编写流式或批式作业。您可以将 Python 主程序上传到资源库，在作业开发页面选择入口文件、配置启动参数和依赖，并按需选择内置运行环境或自定义 Python 虚拟环境。

创建任务前，请先确认目标地域和项目中存在支持 Flink Python 的引擎版本。线上文档当前说明仅 Flink 1.17-volcano 支持 Flink Python 任务；若控制台已提供其他兼容版本，请以实际可选项为准。

将作业主程序上传到项目资源库。主程序可以是单个 .py 文件，也可以是包含多个 Python 模块的 .zip 文件。使用第三方包、自定义 Python 虚拟环境、JAR 包或配置文件时，也应提前准备对应资源。

1. 登录流式计算 Flink 版控制台，在顶部菜单栏选择目标地域。
2. 进入目标项目，在项目左侧导航栏选择作业开发 > 作业开发。
3. 单击加号按钮创建任务。您也可以先选择目标文件夹，或在引导页面选择 Flink Python 作业。
4. 在创建作业对话框中设置作业名称、存储位置和引擎版本，然后单击确定。

配置任务参数 #

任务创建完成后，在任务配置区域设置入口程序、启动参数和 Python 依赖。
图 1　Flink Python 任务配置界面

配置 Entry Point Main Arguments #

KV 模式。​适合逐项维护参数。单击添加，分别填写程序可识别的参数名和值，例如参数名 --input、参数值 s3://bucket/path。需要多个参数时继续添加，提交前确认参数名、值和顺序符合程序的解析规则。
文本模式。​适合直接粘贴完整命令行参数，例如 --input s3://bucket/path --parallelism 4。包含空格或特殊字符的值，应按照程序使用的参数解析方式正确引用或转义。

通过 Python Libraries 使用第三方 Python 包 #

第三方依赖应在与作业运行环境兼容的 Linux 和 Python 版本中安装并打包。下面以 Python 3.10 和 redis==6.1.0 为例。
requirements.txt

redis==6.1.0

build.sh

#!/bin/bash
set -e -x

yum install -y zip

# Python 3.8 可改为 /opt/python/cp38-cp38/bin
PYBIN=/opt/python/cp310-cp310/bin
"${PYBIN}/pip" install --target __deps__ -r requirements.txt
cd __deps__ && zip -r deps.zip . && mv deps.zip ../ && cd ..
rm -rf __deps__

执行以下命令，在兼容的 manylinux 容器中生成 deps.zip。

docker run -it --rm -v $PWD:/build -w /build \
  quay.io/pypa/manylinux_2_28_x86_64 bash ./build.sh

在任务配置页面的 Python Libraries 中添加生成的 deps.zip，保存任务后重新上线或重启作业。若依赖包含 C/C++ 扩展，请特别确认操作系统、CPU 架构和 Python ABI 与运行环境兼容。

通过 Python Archives 使用自定义 Python 虚拟环境 #

平台内置 Python 版本不能满足要求时，可以准备包含 PyFlink 及业务依赖的 Python 虚拟环境，将其打包为 ZIP 并通过 Python Archives 上传。自定义版本必须位于所选 PyFlink 版本支持的 Python 版本范围内。
打包示例（Flink 1.17、Python 3.9）。​在本地新建一个空目录，并在该目录中准备以下三个文件。示例使用 manylinux 容器构建，以降低本地操作系统差异带来的兼容性风险。
1. 准备 requirements.txt
以下内容为 Flink 1.17 虚拟环境示例。Flink 1.17 支持 Python 3.7～3.10；业务所需的其他 Python 包可继续追加到文件末尾。若使用其他 Flink 版本，应按对应版本的 PyFlink 依赖要求调整。

py4j==0.10.9.7
python-dateutil>=2.8.0,<3
apache-beam>=2.43.0,<2.49.0
cloudpickle>=2.2.0
avro-python3>=1.8.1,!=1.9.2
pytz>=2018.3
fastavro>=1.1.0,!=1.8.0
requests>=2.26.0
protobuf>=3.19.0
numpy>=1.21.4
pandas>=1.3.0,<2.3
pyarrow>=5.0.0,<21.0.0
httplib2>=0.19.0
pemja>=0.5.6,<0.5.7;platform_system != "Windows"

2. 准备 init-pyflink-venv.sh
该脚本安装 Miniforge，创建名为 venv 的 Python 3.9 环境，安装依赖并生成 venv.zip。如需其他 Python 版本，可修改 mamba create 命令，但必须使用所选 PyFlink 版本支持的 Python 版本。

#!/bin/bash
set -e

# 下载并安装 Miniforge。
wget "https://github.com/conda-forge/miniforge/releases/download/25.11.0-1/Miniforge3-25.11.0-1-Linux-x86_64.sh" \
  -O "miniforge.sh"
chmod +x miniforge.sh
./miniforge.sh -b
source /root/miniforge3/bin/activate

# 创建 Python 虚拟环境。可按需修改 Python 版本。
mamba create -n venv python=3.9 -y
eval "$(mamba shell hook --shell bash)"
mamba activate venv

# 安装 PyFlink 及业务依赖。
pip install -r /build/requirements.txt

mamba deactivate

# 打包虚拟环境，ZIP 包根目录中保留 venv 目录。
cd /root/miniforge3/envs/
zip -r /root/venv.zip venv

3. 准备 build.sh

#!/bin/bash
set -e -x

yum install -y zip wget

cd /root/
bash /build/init-pyflink-venv.sh
mv venv.zip /build/

4. 执行打包命令
在上述三个文件所在目录执行：

docker run -it --rm \
  -v "$PWD:/build" \
  -w /build \
  quay.io/pypa/manylinux_2_28_x86_64 \
  bash ./build.sh

命令执行完成后，当前目录会生成 venv.zip。可使用 unzip -l venv.zip | head 检查包内目录，确认存在 venv/bin/python。
在 Flink Python 任务中使用虚拟环境

1. 在任务页面的 Python Archives 中添加生成的 venv.zip。
2. 打开配置参数 > 自定义参数，将客户端和 Python worker 的可执行文件指向 ZIP 解压后的 Python。

python.executable: venv.zip/venv/bin/python
python.client.executable: venv.zip/venv/bin/python

保存任务并重新上线或重启。若启动失败，请先检查 ZIP 内目录层级与配置路径是否一致，再检查虚拟环境的 Linux、CPU 架构、Python 版本和所选 Flink/PyFlink 版本是否兼容。

在任务开发页面右侧打开配置参数，展开运行环境配置。在此处可以选择内置 Python 版本和 JDK 版本，并按页面提供的选项配置 Connector 版本。
图 2　配置参数中的运行环境配置

选择运行环境后，再构建或上传第三方包和虚拟环境。不要在 Python 3.8 环境中构建含本地扩展的依赖后直接用于 Python 3.10，也不要忽略 JDK 与 Connector/JAR 的版本兼容关系。

使用 JAR 包 #

Python 作业使用 Connector、Java 类或 Java 自定义函数时，打开配置参数 > 依赖文件，选择已上传的 JAR 包或上传新资源，保存配置后重新上线或重启任务。

使用普通文件 #

需要解压或保留目录结构。​将文件打包为 ZIP，通过 Python Archives 添加。平台会在容器中解压，程序通过相对路径访问。例如将 config.yaml 打包到 data.zip 后，可按实际解压目录读取 data.zip/config.yaml。
单一文件且不需要解压。​通过配置参数 > 依赖文件添加。依赖文件会放到 /opt/tiger/workdir，程序可使用绝对路径访问，例如 /opt/tiger/workdir/config.yaml。

创建批式 Python 任务时，在作业开发页面选择批式任务入口，设置任务名称、任务类型、作业模板、所属文件夹和支持的引擎版本。进入任务编辑页面后，Python File URI、Entry Module、Entry Point Main Arguments、Python Libraries、Python Archives 和运行环境配置的填写方式与前文一致。

1. 检查 Python File URI、Entry Module 和启动参数是否与程序入口一致。
2. 检查 Python Libraries、Python Archives、依赖 JAR 和普通文件是否完整。
3. 确认 Python、JDK 和 Connector/JAR 版本兼容。
4. 单击保存，完成开发后将任务上线；已上线任务修改配置后需要按页面提示重启。
5. 在任务运维页面检查启动状态和日志。出现 ModuleNotFoundError 时优先检查 Python Libraries；出现 Python 可执行文件找不到时检查 Archives 目录层级和 python.executable；出现 Java 类找不到时检查依赖 JAR。

Flink 1.17 版本中 Python 3.8 和 3.10 环境内置支持以下依赖库。您可以不用打包，直接使用。

Package            Version
------------------ ------------
apache-flink       1.17.2
apache-beam        2.48.0
avro-python3       1.10.2
certifi            2026.2.25
charset-normalizer 3.4.6
cloudpickle        2.2.1
crcmod             1.7
dill               0.3.1.1
dnspython          2.6.1
docopt             0.6.2
fastavro           1.9.7
fasteners          0.20
find_libpython     0.4.1
grpcio             1.70.0
hdfs               2.7.3
httplib2           0.22.0
idna               3.11
numpy              1.24.4
objsize            0.6.1
orjson             3.10.15
pandas             2.0.3
pemja              0.5.6
pip                23.0.1
proto-plus         1.27.1
protobuf           4.23.4
py4j               0.10.9.7
pyarrow            11.0.0
pydot              1.4.2
pymongo            4.10.1
pyparsing          3.1.4
python-dateutil    2.9.0.post0
pytz               2026.1.post1
regex              2024.11.6
requests           2.32.4
setuptools         56.0.0
six                1.17.0
typing_extensions  4.13.2
tzdata             2025.3
urllib3            2.2.3
zstandard          0.23.0

Package            Version
------------------ ------------
apache-flink       1.17.2
apache-beam        2.48.0
avro-python3       1.10.2
certifi            2026.2.25
charset-normalizer 3.4.6
cloudpickle        2.2.1
crcmod             1.7
dill               0.3.1.1
dnspython          2.8.0
docopt             0.6.2
fastavro           1.12.1
fasteners          0.20
find_libpython     0.5.1
grpcio             1.78.0
hdfs               2.7.3
httplib2           0.22.0
idna               3.11
numpy              1.24.4
objsize            0.6.1
orjson             3.11.7
pandas             2.2.3
pemja              0.5.6
pip                23.0.1
proto-plus         1.27.1
protobuf           4.23.4
py4j               0.10.9.7
pyarrow            11.0.0
pydot              1.4.2
pymongo            4.16.0
pyparsing          3.3.2
python-dateutil    2.9.0.post0
pytz               2026.1.post1
regex              2026.2.28
requests           2.33.1
setuptools         65.5.0
six                1.17.0
typing_extensions  4.15.0
tzdata             2025.3
urllib3            2.6.3
zstandard          0.25.0