test: compiled python version (#503)

* test: compiled python example

* docs: note about compiled python version

* test: also enable py compilation for the latest versions

* test: snapshot update

core/__snapshots__/TestGenerateBuildPlanForExamples_python-compiled_1.snap.json

@@ -0,0 +1,149 @@
+{
+ "caches": {
+  "pip": {
+   "directory": "/opt/pip-cache",
+   "type": "shared"
+  }
+ },
+ "deploy": {
+  "base": {
+   "image": "ghcr.io/railwayapp/railpack-runtime:mise-2026.3.8"
+  },
+  "inputs": [
+   {
+    "include": [
+     "/mise/shims",
+     "/mise/installs",
+     "/usr/local/bin/mise",
+     "/etc/mise/config.toml",
+     "/root/.local/state/mise"
+    ],
+    "step": "packages:mise"
+   },
+   {
+    "include": [
+     "/app/.venv"
+    ],
+    "step": "build"
+   },
+   {
+    "exclude": [
+     ".venv"
+    ],
+    "include": [
+     "."
+    ],
+    "step": "build"
+   }
+  ],
+  "startCommand": "python main.py",
+  "variables": {
+   "PIP_DEFAULT_TIMEOUT": "100",
+   "PIP_DISABLE_PIP_VERSION_CHECK": "1",
+   "PYTHONDONTWRITEBYTECODE": "1",
+   "PYTHONFAULTHANDLER": "1",
+   "PYTHONHASHSEED": "random",
+   "PYTHONUNBUFFERED": "1"
+  }
+ },
+ "steps": [
+  {
+   "assets": {
+    "mise.toml": "[mise.toml]"
+   },
+   "commands": [
+    {
+     "path": "/mise/shims"
+    },
+    {
+     "dest": "mise.toml",
+     "src": "mise.toml"
+    },
+    {
+     "customName": "create mise config",
+     "name": "mise.toml",
+     "path": "/etc/mise/config.toml"
+    },
+    {
+     "cmd": "mise install",
+     "customName": "install mise packages: python"
+    }
+   ],
+   "inputs": [
+    {
+     "image": "ghcr.io/railwayapp/railpack-builder:mise-2026.3.8"
+    }
+   ],
+   "name": "packages:mise",
+   "variables": {
+    "MISE_CACHE_DIR": "/mise/cache",
+    "MISE_CONFIG_DIR": "/mise",
+    "MISE_DATA_DIR": "/mise",
+    "MISE_IDIOMATIC_VERSION_FILE_ENABLE_TOOLS": "python,node,ruby,elixir,go,java,yarn",
+    "MISE_INSTALLS_DIR": "/mise/installs",
+    "MISE_NODE_VERIFY": "false",
+    "MISE_PARANOID": "1",
+    "MISE_PYTHON_COMPILE": "false",
+    "MISE_SHIMS_DIR": "/mise/shims",
+    "MISE_TRUSTED_CONFIG_PATHS": "/app"
+   }
+  },
+  {
+   "caches": [
+    "pip"
+   ],
+   "commands": [
+    {
+     "cmd": "python -m venv /app/.venv"
+    },
+    {
+     "path": "/app/.venv/bin"
+    },
+    {
+     "dest": "requirements.txt",
+     "src": "requirements.txt"
+    },
+    {
+     "dest": "pyproject.toml",
+     "src": "pyproject.toml"
+    },
+    {
+     "cmd": "pip install -r requirements.txt"
+    }
+   ],
+   "inputs": [
+    {
+     "step": "packages:mise"
+    }
+   ],
+   "name": "install",
+   "variables": {
+    "PIP_CACHE_DIR": "/opt/pip-cache",
+    "PIP_DEFAULT_TIMEOUT": "100",
+    "PIP_DISABLE_PIP_VERSION_CHECK": "1",
+    "PYTHONDONTWRITEBYTECODE": "1",
+    "PYTHONFAULTHANDLER": "1",
+    "PYTHONHASHSEED": "random",
+    "PYTHONUNBUFFERED": "1",
+    "VIRTUAL_ENV": "/app/.venv"
+   }
+  },
+  {
+   "inputs": [
+    {
+     "step": "install"
+    },
+    {
+     "include": [
+      "."
+     ],
+     "local": true
+    }
+   ],
+   "name": "build",
+   "secrets": [
+    "*"
+   ]
+  }
+ ]
+}

docs/src/content/docs/languages/python.md

@@ -30,6 +30,34 @@ The Python version is determined in the following order:
 - Read from the `Pipfile` if present
 - Defaults to `3.13.2`
 
+## Precompiled vs. Compiled Python
+
+By default, Railpack installs Python using precompiled binaries via Mise.
+Precompiled binaries are faster to install and more reliable, but they may not
+be available for every Python version (e.g., very new or very old releases).
+
+When a precompiled binary is unavailable, the build will fail. This is
+intentional — many popular packages that provide precompiled wheels have not
+yet caught up to the latest Python release, meaning pip will fall back to
+compiling those packages from source, which frequently fails.
+
+If you need to use a Python version without a precompiled binary and are
+prepared to handle any compilation issues that may arise, you can opt into
+source compilation:
+
+```sh
+MISE_PYTHON_COMPILE=1
+```
+
+Set this as a deploy environment variable
+
+:::caution
+Compiling Python and its packages from source significantly increases build
+times and may cause failures for packages that have complex native
+dependencies. Only use this if a precompiled binary is unavailable for your
+required version.
+:::
+
 ## Runtime Variables
 
 These variables are available at runtime:
@@ -134,4 +162,4 @@ Railpack automatically installs system dependencies for common databases:
 
 ## BuildKit Caching
 
-The Python provider will cache `/opt/pip-cache` under the cache key `pip`, and, for `uv`-based apps, `/opt/uv-cache` under the key `uv`.
+The Python provider will cache `/opt/pip-cache` under the cache key `pip`, and, for `uv`-based apps, `/opt/uv-cache` under the key `uv`.

examples/python-compiled/README.md

@@ -0,0 +1 @@
+Test to make sure we can still compile older python versions and the user is able to override our defaults.

examples/python-compiled/main.py

@@ -0,0 +1,3 @@
+import sys
+
+print(f'Python version: {sys.version.split()[0]}')

examples/python-compiled/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+python = "3.7"

examples/python-compiled/pyproject.toml

@@ -0,0 +1,5 @@
+[project]
+name = "python-latest"
+version = "0.1.0"
+description = "Test compiled python support"
+requires-python = ">=3.9"

examples/python-compiled/requirements.txt

@@ -0,0 +1 @@
+pandas

examples/python-compiled/test.json

@@ -0,0 +1,8 @@
+[
+  {
+    "expectedOutput": "Python version: 3.7",
+    "envs": {
+    	"MISE_PYTHON_COMPILE": "1"
+    }
+  }
+]

examples/python-latest/test.json

@@ -1,5 +1,9 @@
 [
   {
-    "expectedOutput": "Python version: 3."
+    "expectedOutput": "Python version: 3.",
+    "envs": {
+	    // allow compiled python for the absolute latest versions of python
+    	"MISE_PYTHON_COMPILE": "1"
+    }
   }
 ]