From fb53ab911ed8f3fb54c130c58b071f8f202ae865 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=B3bert=20Hubin=C3=A1k?= <rhubinak@tuta.io>
Date: Mon, 15 Dec 2025 14:57:31 +0000
Subject: [PATCH] Add 'uv' as an alternative to 'Pyenv' for Python versioning

Updated instructions to include 'uv' as an alternative to 'Pyenv' for managing Python versions. Added detailed steps for using 'uv' in the build hook and runtime environment.
---
 .../src/languages/python/python-version.md    | 63 ++++++++++++++++++-
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/sites/upsun/src/languages/python/python-version.md b/sites/upsun/src/languages/python/python-version.md
index 7884601355..a88854b2bd 100644
--- a/sites/upsun/src/languages/python/python-version.md
+++ b/sites/upsun/src/languages/python/python-version.md
@@ -10,8 +10,67 @@ description: See how to manage different Python versions in your {{% vendor/name
 You may need to use a specific version of Python that isn't available in an app container for a different language.
 For example, a container might have a long-term support version, while you want the latest version.
 
-In such cases, use the [Pyenv version manager](https://github.com/pyenv/pyenv)
-to install the specific version you want to use.
+In such cases, use [uv](https://docs.astral.sh/uv/) or [Pyenv](https://github.com/pyenv/pyenv) version manager to install the specific version you want to use.
+
+## uv
+
+1.  Add your target Python version as a [variable](../../development/variables/_index.md):
+
+```yaml {configFile="app"}
+applications:
+  # The app's name, which must be unique within the project.
+  myapp:
+    type: 'php:{{% latest "php" %}}'
+    variables:
+      env:
+        # Update for your desired Python version.
+        PYTHON_VERSION: "3.11"
+```
+2.  Add uv in a [`build` hook](../../create-apps/hooks/hooks-comparison.md#build-hook):
+
+```yaml {configFile="app"}
+applications:
+  # The app's name, which must be unique within the project.
+  myapp:
+    type: 'php:{{% latest "php" %}}'
+    variables:
+      env:
+        # Update for your desired Python version.
+        PYTHON_VERSION: "3.11"
+    hooks:
+      build: |
+        # Exit the hook on any failure
+        set -e
+
+        # Install uv
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+
+        # Install a specific Python version
+        /app/.local/bin/uv python install $PYTHON_VERSION
+
+        # Install a package using specific Python version
+        /app/.local/bin/uv tool install --python $PYTHON_VERSION weasyprint
+```
+Now your build hook can use the specified version of Python.
+You can verify this by running `python --version`.
+
+If you want this Python version to be available in the runtime environment, follow these steps:
+
+1.  Create an [`.environment` file](../../development/variables/set-variables.md#set-variables-via-script):
+
+    ```bash
+    touch .environment
+    ```
+
+2.  Alias python for the runtime environment:
+
+    ```yaml {location=".environment"}
+    alias python=/app/.local/bin/python3.11
+    ```
+
+Now the specified Python version is used in the runtime environment.
+
+## Pyenv
 
 1.  Add your target Python version as a [variable](../../development/variables/_index.md):