指定 Python 依赖项

使用以下任一方法，为受支持的 Python 版本指定应用依赖项：

• 在根目录中使用 requirements.txt 文件。此文件必须与包含源代码的 main.py 文件位于同一目录中。在 requirements.txt 文件中，每个软件包对应一行内容。每行包含软件包名称和（可选）请求的版本。为了防止 build 受到依赖项版本更改的影响，请考虑将依赖项软件包固定到特定版本。

  下面是一个 requirements.txt 文件示例：

  functions-framework
  requests==2.20.0
  numpy
  

• 使用 pyproject.toml 文件指定依赖项。如果您在 pyproject.toml 文件中（而不是在 requirements.txt 文件中）管理应用依赖项，则 Python buildpack 会根据您在 pyproject.toml 文件中指定的配置来确定软件包管理系统。如需了解详情，请参阅使用 pyproject.toml 文件部署 Python 应用。

  如果您的应用同时使用 pyproject.toml 文件和 requirements.txt 文件，则 requirements.txt 文件的优先级更高。

  • 下面是一个 pyproject.toml 文件示例：

    [project]
    name = "demo-app"
    version = "0.1.0"
    description = ""
    requires-python = ">=3.10"
    dependencies = [
        "flask>=3.1.1",
        "gunicorn>=23.0.0",
    ]
    
    [build-system]
    requires = ["setuptools>=61.0"]
    build-backend = "setuptools.build_meta"
    

• 将本地依赖项与函数一起打包。

  不支持使用 Pipfile/Pipfile.lock 标准的依赖项规范。您的项目不应包含这些文件。

  如果您使用 requirements.txt 文件来管理依赖项，那么在您创建函数时，Cloud Run 会代表您安装 Functions Framework。不过，我们建议您将 Functions 框架添加为显式依赖项，以避免出现差异。

  使用 pyproject.toml 文件时，您必须将 Functions 框架作为依赖项包含在内，因为 Cloud Run 不会为您安装该框架。

软件包管理器

如果您使用 requirements.txt file 管理依赖项，默认的软件包管理系统会因您配置的 Python 版本而异。

如果您使用 pyproject.toml 文件（而非 requirements.txt 文件）来管理依赖项，Python buildpack 会根据 pyproject.toml 文件中的配置设置来确定软件包管理系统。buildpack 支持 pip、uv 和 Poetry 软件包管理系统。如需了解详情，请参阅使用 pyproject.toml 文件部署 Python 应用。

Python 3.14 及更高版本

从 Python 3.14 版（预览版）开始，Python buildpack 使用 uv 软件包管理系统作为您在 requirements.txt 文件中指定的依赖项的默认安装程序。

如需使用 pip 作为软件包管理系统，请配置环境变量 GOOGLE_PYTHON_PACKAGE_MANAGER="pip"。

运行 gcloud run deploy 命令，将软件包管理器的环境变量设置为 pip：

gcloud run deploy SERVICE --source . \
  --set-build-env-vars=GOOGLE_PYTHON_PACKAGE_MANAGER=pip

将 SERVICE 替换为您的 Cloud Run 服务的名称。

Python 3.13 及更低版本

对于 Python 3.13 版及更低版本，Python buildpack 会使用 pip 软件包管理系统来安装您在 requirements.txt 文件中定义的依赖项。

如需使用 uv（预览版）作为软件包管理系统，请配置环境变量 GOOGLE_PYTHON_PACKAGE_MANAGER="uv"。

运行 gcloud beta run deploy 命令，将软件包管理器的环境变量设置为 uv：

gcloud beta run deploy SERVICE --source . \
  --set-build-env-vars=GOOGLE_PYTHON_PACKAGE_MANAGER=uv

将 SERVICE 替换为您的 Cloud Run 服务的名称。

打包本地依赖项

将依赖项与函数一起打包并进行部署。如果您在使用受支持的软件包管理系统时无法获取依赖项，或者您的 Cloud Run 环境的互联网访问受限，则此方法很有用。

您还可以使用 requirements.txt 文件来指定尚未与函数封装在一起的其他依赖项。例如，您可以使用以下目录结构：

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

使用以下 import 语句从 localpackage 导入代码：

# code in main.py
from localpackage import script

此方法不会运行任何 setup.py 文件。您可以捆绑包含这些文件的软件包，但该软件包可能无法在 Cloud Run functions 上正常运行。

复制的依赖项

已复制的依赖项是其源代码直接包含在源代码包中并与您自己的代码一起重新构建的依赖项。使用 GOOGLE_VENDOR_PIP_DEPENDENCIES build 环境变量创建已复制的 pip 依赖项，并避免在部署期间安装这些依赖项。

创建复制的依赖项

1. 确保您的开发系统上安装了 python3。

2. 在开发树根目录下的 requirements.txt 文件中声明您的应用依赖项。

3. 通过在 requirements.txt 文件中的单独行添加 functions-framework，将 Functions 框架声明为要求。

4. 将函数的依赖项下载到本地目录。执行此操作的步骤取决于依赖项是 Python wheel (*.whl) 文件还是 tar 文件 (*.tar.gz)。

   1. 如果依赖项是 Python wheel (*.whl)，请使用以下 pip 命令将其下载到开发树的根目录中：

      python3 -m pip download -r requirements.txt --only-binary=:all: \
         -d DIRECTORY \
         --python-version PYTHON_RUNTIME_VERSION \
         --platform manylinux2014_x86_64 \
         --implementation cp
      

      替换以下内容：

      • DIRECTORY：要下载到的本地目录的名称。
      • PYTHON_RUNTIME_VERSION：用于兼容性检查的 Python 版本。例如，314 for Python 3.14。
        此版本必须与某个支持的 Python 运行时匹配。

      生成的目录结构应如下所示：

      myfunction/
      ├── main.py
      └── requirements.txt
      └── DIRECTORY
         ├── dependency1.whl
         └── dependency2.whl
      

   2. 如果依赖项是 tar 文件 (*.tar.gz)，则：

      1. 如果依赖项是用 Python 编写的，请使用 pip 下载它：

         python3 -m pip download -r requirements.txt \
            -d DIRECTORY
         

      2. 如果依赖项包含使用 C 或 C++ 编写的代码，请单独下载并编译该代码。

5. 部署函数及其已复制的依赖项：

   gcloud functions deploy FUNCTION_NAME \
     --runtime PYTHON_RUNTIME_NAME \
     --set-build-env-vars GOOGLE_VENDOR_PIP_DEPENDENCIES=DIRECTORY
   

   替换以下内容：

   • FUNCTION_NAME：要部署的函数的名称。
   • PYTHON_RUNTIME_NAME：一个支持的 Python 运行时的名称，用于运行已部署的函数，例如 python311。该名称必须与您在本地开发环境中使用的 Python 运行时版本相同。
   • DIRECTORY：包含复制的依赖项的目录的名称。

如需详细了解如何使用 Buildpack，请参阅使用 Buildpack 构建函数。

使用专用依赖项

您可以使用来自 Artifact Registry 或其他仓库的专用依赖项。

来自 Artifact Registry 的专用依赖项

Artifact Registry Python 制品库可以为您的 Python 函数托管专用依赖项。部署到 Cloud Run 时，构建流程将自动为 Cloud Build 服务账号生成 Artifact Registry 凭证。在 requirements.txt 中添加 Artifact Registry 网址，而不需要生成其他凭证。例如：

--index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

如果您的构建需要多个代码库，请使用 Artifact Registry 虚拟代码库来安全地控制 pip 搜索代码库的顺序。

来自其他代码库的专用依赖项

Buildpack 在 Cloud Build 环境中安装依赖项，该环境不提供对 SSH 密钥的访问权限。复制您在需要基于 SSH 的身份验证的代码库中托管的软件包，并与项目代码一起上传这些软件包。

您可以先使用带有 -t DIRECTORY 标志的 pip install 命令将专用依赖项复制到本地目录，然后再部署应用，如下所述：

1. 将依赖项复制到本地目录：

   pip install -t DIRECTORY DEPENDENCY

2. 将空 __init__.py 文件添加到 DIRECTORY 目录，以将其转换为模块。
3. 从此模块中导入依赖项以进行使用：

   import DIRECTORY.DEPENDENCY

预装软件包

在您部署函数时，Python buildpack 会安装以下 Python 软件包。如果您的函数代码中使用其中任何软件包，请将以下版本添加到 requirements.txt 文件中：

为避免依赖项版本更新导致问题，请将软件包固定到特定版本。

anyio==4.5.2
blinker==1.8.2
click==8.1.8
cloudevents==1.11.0
deprecation==2.1.0
exceptiongroup==1.3.0
Flask==3.0.3
functions-framework==3.9.1
gunicorn==23.0.0
h11==0.16.0
idna==3.10
importlib_metadata==8.5.0
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==2.1.5
packaging==25.0
sniffio==1.3.1
# Install starlette 0.44.0 for Python 3.8
starlette==0.44.0; python_version == '3.8'
# Install starlette 0.49.1 for Python versions greater than 3.8
starlette==0.49.1; python_version > '3.8'
typing_extensions==4.13.2
uvicorn==0.33.0
uvicorn-worker==0.2.0
watchdog==4.0.2
Werkzeug==3.0.6
zipp==3.20.2

Python buildpack 会安装以下固定到特定版本的软件包：

• pip（最新版本）
• setuptools（最新版本）
• wheel（由产品要求决定）

Python 运行时还会在执行环境中添加多个系统软件包。