Membangun aplikasi Python

Buildpack mendukung konfigurasi bahasa idiomatis melalui variabel lingkungan.

Menentukan versi Python

Secara default, buildpack Python Runtime menggunakan penafsir Python versi stabil terbaru. Jika aplikasi memerlukan versi tertentu, Anda dapat menentukannya dengan menyertakan file .python-version dalam direktori root aplikasi.

3.14

Gunakan GOOGLE_PYTHON_VERSION

Anda juga dapat menentukan versi Python menggunakan variabel lingkungan GOOGLE_PYTHON_VERSION. Jika kedua konfigurasi ditetapkan, nilai GOOGLE_PYTHON_VERSION akan lebih diprioritaskan daripada file .python-version. Secara default, jika file .python-version dan variabel lingkungan GOOGLE_PYTHON_VERSION tidak ditentukan, versi LTS terbaru Python akan digunakan.

Untuk mengonfigurasi buildpack agar menggunakan Python 3.13 saat men-deploy aplikasi Anda:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env GOOGLE_PYTHON_VERSION="3.14.x"

Anda juga dapat menggunakan deskriptor project project.toml untuk mengenkode variabel lingkungan bersama file project Anda. Lihat petunjuk cara membangun aplikasi dengan variabel lingkungan.

Menentukan dependensi

Tentukan dependensi aplikasi Anda untuk versi Python yang didukung menggunakan salah satu pendekatan berikut:

• Gunakan file requirements.txt di direktori root. File ini harus berada di direktori yang sama dengan file main.py yang berisi kode sumber Anda. File requirements.txt berisi satu baris per paket. Setiap baris berisi nama paket, dan secara opsional, versi yang diminta. Agar build Anda tidak terpengaruh oleh perubahan versi dependensi, pertimbangkan untuk menyematkan paket dependensi ke versi tertentu.

  Berikut adalah contoh file requirements.txt:

  functions-framework
  requests==2.20.0
  numpy
  

• Gunakan file pyproject.toml untuk menentukan dependensi. Jika Anda mengelola dependensi aplikasi dalam file pyproject.toml, bukan file requirements.txt, buildpack Python akan menentukan pengelola paket berdasarkan konfigurasi yang Anda tentukan dalam file pyproject.toml. Untuk mengetahui informasi selengkapnya, lihat Men-deploy aplikasi Python dengan file pyproject.toml.

  Jika aplikasi Anda menggunakan file pyproject.toml dan file requirements.txt, file requirements.txt akan diprioritaskan.

  • Berikut adalah contoh file 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"
    

Pengelola paket

Jika Anda mengelola dependensi menggunakan requirements.txt file, pengelola paket default akan bervariasi berdasarkan versi Python yang Anda konfigurasi.

Jika Anda menggunakan file pyproject.toml untuk mengelola dependensi, bukan file requirements.txt, buildpack Python akan menentukan pengelola paket berdasarkan setelan konfigurasi Anda dalam file pyproject.toml. Buildpack mendukung pengelola paket pip, uv, dan Poetry. Untuk mengetahui informasi selengkapnya, lihat Men-deploy aplikasi Python dengan file pyproject.toml.

Python 3.14 dan yang lebih baru

Mulai dari Python versi 3.14 (pratinjau) dan yang lebih baru, buildpack Python menggunakan pengelola paket uv sebagai penginstal default untuk dependensi yang Anda tentukan dalam file requirements.txt.

Untuk menggunakan pip sebagai pengelola paket, konfigurasi variabel lingkungan GOOGLE_PYTHON_PACKAGE_MANAGER="pip".

Python 3.13 dan yang lebih lama

Untuk Python versi 3.13 dan yang lebih lama, buildpack Python menggunakan pengelola paket pip untuk menginstal dependensi yang Anda tentukan dalam file requirements.txt.

Untuk menggunakan uv (pratinjau) sebagai pengelola paket, konfigurasi variabel lingkungan GOOGLE_PYTHON_PACKAGE_MANAGER="uv".

Mengonfigurasi pip

Perilaku pip dapat dikonfigurasi menggunakan variabel lingkungan:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env PIP_DEFAULT_TIMEOUT='60'

Dependensi pribadi dari Artifact Registry

Repositori Python Artifact Registry dapat menghosting dependensi pribadi untuk fungsi Python Anda. Saat membangun aplikasi di Cloud Build, buildpack Python akan otomatis membuat kredensial Artifact Registry untuk akun layanan Cloud Build. Anda hanya perlu menyertakan URL Artifact Registry di requirements.txt tanpa membuat kredensial tambahan. Contoh:

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

Titik entri aplikasi

Bagian berikut menjelaskan titik entri default untuk buildpack Python.

Titik entri untuk deployment sumber Cloud Run

Fitur ini hanya tersedia jika Anda men-deploy kode sumber ke Cloud Run dengan runtime Python. Fitur ini tidak berlaku jika Anda membangun image container secara langsung menggunakan pack build di luar proses deployment sumber Cloud Run.

Buildpack Python mendukung framework web modern seperti FastAPI, Gradio, dan Streamlit.

Python versi 3.12 dan yang lebih lama

Jika Anda menggunakan Python versi 3.12 dan yang lebih lama, buildpack Python secara default menggunakan Gunicorn sebagai server HTTP WSGI untuk workload Anda. Buildpack Python menetapkan titik entri default ke gunicorn -b :8080 main:app.

Python versi 3.13 dan yang lebih baru

Untuk Python versi 3.13 dan yang lebih baru, buildpack Python menetapkan titik entri default untuk deployment sumber Cloud Run berdasarkan konfigurasi framework atau server web di file requirements.txt Anda. Setelan default ini hanya berlaku untuk deployment sumber layanan Cloud Run, bukan untuk Cloud Run functions.

Saat Anda men-deploy layanan Cloud Run dari sumber menggunakan runtime Python, buildpack menentukan versi Python dan titik entri default dengan cara berikut:

• Jika Anda tidak menentukan versi Python dalam file sumber, buildpack Python akan menyetel default ke versi Python terbaru yang didukung. Buildpack menentukan titik entri default berdasarkan server web atau framework yang telah Anda konfigurasi dalam file requirements.txt.

• Jika Anda tidak menentukan server web atau framework dalam file requirements.txt, buildpack Python akan menggunakan Gunicorn secara default sebagai server HTTP WSGI untuk workload Anda. Buildpack Python menetapkan titik entri default ke gunicorn -b :8080 main:app.

• Buildpack Python menetapkan titik entri default berdasarkan urutan prioritas berikut, seperti yang ditentukan dalam file requirements.txt:

  1. gunicorn
  2. uvicorn
  3. fastapi[standard]
  4. gradio
  5. streamlit

Mengonfigurasi server web atau framework

Untuk setiap konfigurasi Python umum dalam file requirements.txt, tabel berikut menunjukkan titik entri default saat men-deploy ke Cloud Run dari sumber:

Konfigurasi utama	Titik entri default	Variabel lingkungan
gunicorn	gunicorn -b :8080 main:app
numpy	gunicorn -b :8080 main:app
fastapi uvicorn	uvicorn main:app --host 0.0.0.0 --port 8080
fastapi[standard]	uvicorn main:app --host 0.0.0.0 --port 8080
uvicorn gunicorn	gunicorn -b :8080 main:app
gradio	python main.py	GRADIO_SERVER_NAME=0.0.0.0 GRADIO_SERVER_PORT=8080
streamlit	streamlit run main.py --server.address 0.0.0.0 --server.port 8080

Untuk menghindari kegagalan deployment, gunakan versi Python yang didukung di file sumber Anda, dan tentukan server web di file requirements.txt Anda.

Atau, Anda juga dapat menentukan titik entri dengan menjalankan perintah deployment sumber berikut:

  gcloud run deploy SERVICE --source .  --set-build-env-vars GOOGLE_ENTRYPOINT="ENTRYPOINT"

Ganti kode berikut:

• SERVICE: nama layanan yang ingin Anda deploy.
• ENTRYPOINT: titik entri default yang ingin Anda gunakan untuk kode sumber.

Jika Anda tidak dapat men-deploy kode sumber ke Cloud Run atau menemukan error dalam log, lihat panduan pemecahan masalah Cloud Run.

Titik entri untuk semua deployment lainnya

Buildpack Python menggunakan Gunicorn sebagai server HTTP WSGI default untuk workload Anda. Aplikasi yang dibangun dengan buildpack Python memulai proses gunicorn dengan setelan default, mirip dengan menjalankan:

gunicorn --bind :8080 main:app

Menyesuaikan titik entri aplikasi

Anda dapat menyesuaikan perintah memulai aplikasi menggunakan Procfile atau variabel lingkungan. Anda mungkin perlu melakukannya untuk menyesuaikan konfigurasi titik entri default.

Anda dapat membuat Procfile dengan setelan kustom di direktori root. Contoh:

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

Penting: Saat mengganti default Gunicorn, Anda harus menyertakan gunicorn sebagai dependensi paket dalam file requirements.txt project Anda.

Atau, Anda dapat menggunakan variabel lingkungan GOOGLE_ENTRYPOINT dengan perintah pack. Contoh:

pack build sample-python \
  --builder gcr.io/buildpacks/builder
  --env "GOOGLE_ENTRYPOINT='gunicorn --bind :$PORT main:app'"

Variabel Lingkungan

Buildpack Python mendukung variabel lingkungan berikut untuk menyesuaikan container Anda

PIP_<key>

Lihat dokumentasi pip.

Contoh: PIP_DEFAULT_TIMEOUT=60 menetapkan --default-timeout=60 untuk perintah pip.

Men-deploy aplikasi Python dengan file pyproject.toml

Pratinjau — Deploy Python applications to Cloud Run and Cloud Run functions with a pyproject.toml file

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Buildpack Python mendukung project yang Anda konfigurasi dengan file pyproject.toml. Dengan fitur ini, Anda dapat men-deploy aplikasi yang dikelola dengan Poetry, uv, atau pip, langsung ke Cloud Run dan Cloud Run Functions. Fitur ini tidak tersedia di App Engine.

Buildpack Python hanya menggunakan file pyproject.toml jika tidak ada file requirements.txt di direktori root Anda. Jika aplikasi Anda menggunakan file pyproject.toml dan file requirements.txt, maka file requirements.txt akan lebih diutamakan.

Konfigurasi buildpack yang didukung

Buildpack Python mendukung konfigurasi berikut:

• pip buildpack: Menginstal dependensi langsung dari pyproject.toml jika mendeteksi semua kondisi berikut:

  • File pyproject.toml ada di direktori root dan Anda tidak mengonfigurasi alat dengan prioritas tinggi seperti file poetry.lock, bagian [tool.poetry], atau file uv.lock.

  • Anda menetapkan variabel lingkungan GOOGLE_PYTHON_PACKAGE_MANAGER ke pip.

• uv buildpack: Mendukung project Python yang Anda kelola dengan uv. Buildpack ini diaktifkan jika mendeteksi salah satu kondisi berikut:

  • File uv.lock dan file pyproject.toml ada di root project.
  • File pyproject.toml ada di root project, dan Anda menetapkan variabel lingkungan GOOGLE_PYTHON_PACKAGE_MANAGER ke uv.
  • File pyproject.toml ada dan Anda tidak menyertakan file kunci lain dengan prioritas tinggi seperti poetry.lock, uv.lock, atau konfigurasi seperti [tool.poetry], dan Anda tidak menetapkan variabel lingkungan GOOGLE_PYTHON_PACKAGE_MANAGER.

• Buildpack Poetry: Mendukung project Python yang Anda kelola dengan Poetry. Buildpack ini akan aktif jika mendeteksi salah satu kondisi berikut:

  • File poetry.lock dan file pyproject.toml ada di root project.
  • File pyproject.toml ada di root project dan bagian [tool.poetry] ada di file pyproject.toml.

Prioritas pengelola paket

Buildpack Python menentukan pengelola paket default berdasarkan konfigurasi dalam urutan prioritas berikut:

1. File requirements.txt akan diberi prioritas tertinggi. Hanya jika file ini ada, buildpack Python akan menggunakan pengelola paket default untuk menginstal dependensi pada langkah build. Jika file requirements.txt tidak ada, proses deteksi akan melanjutkan ke langkah berikutnya.

2. Kemudian, buildpack memeriksa file pyproject.toml untuk menemukan file poetry.lock atau bagian [tool.poetry]. Jika ditemukan, proses build akan dilanjutkan menggunakan Poetry untuk menginstal dependensi.

3. Jika konfigurasi Poetry tidak terdeteksi, buildpack akan memeriksa file uv.lock. Jika ditemukan, proses build akan menggunakan uv untuk menginstal dependensi.

4. Jika file kunci tidak ada, buildpack akan memeriksa variabel lingkungan GOOGLE_PYTHON_PACKAGE_MANAGER untuk konfigurasi pip atau uv.

5. Default. Jika Anda tidak menetapkan variabel lingkungan, dan hanya menggunakan file pyproject.toml tanpa uv atau Poetry, buildpack akan menggunakan uv secara default untuk semua versi Python yang didukung.

Titik entri dengan file pyproject.toml

Saat Anda men-deploy aplikasi dengan file pyproject.toml, bukan menggunakan file requirements.txt, buildpack Python akan menggunakan metode lain untuk menentukan titik entri. Untuk mengetahui informasi tentang cara mengonfigurasi titik entri aplikasi dengan file requirements.txt, lihat Titik entri aplikasi.

Buildpack menelusuri titik entri dalam urutan prioritas berikut:

1. Jika Procfile ada di direktori root Anda, atau Anda mengonfigurasi variabel lingkungan GOOGLE_ENTRYPOINT, konfigurasi ini akan selalu menggantikan titik entri yang ditentukan oleh skrip pyproject.toml.

2. Buildpack Python menggunakan skrip kustom yang Anda konfigurasi di bagian [tool.poetry.scripts] dan [project.scripts]. Jika Anda mengonfigurasi skrip yang menyertakan start, ini adalah titik entri Anda. Misalnya, poetry run start atau uv run start.

3. Jika Anda tidak mengonfigurasi skrip start, tetapi Anda menentukan skrip lain, skrip yang Anda tentukan adalah titik entri default. Misalnya, poetry run mycmd atau uv run mycmd.

Tidak seperti build berbasis requirements.txt, buildpack Python tidak otomatis menginstal gunicorn untuk project pyproject.toml. Untuk menggunakan gunicorn atau server lainnya, Anda harus menambahkannya secara eksplisit ke dependensi dalam file pyproject.toml.

Jika Anda tidak mengonfigurasi skrip kustom dalam file pyproject.toml, buildpack akan mencoba mendeteksi framework umum, seperti gunicorn, uvicorn, atau fastapi dari dependensi pyproject.toml Anda dan menentukan titik entri default.