💡 Originally published on Bijak Technology Enterprise Journal with full interactive parameter benchmarks.
ADR-009: Migrating Package Management and Python Runtime to Astral UV on Integrated VPS
Status: Accepted
Date: February 2026
Architectural Context: Our Python microservices deployment pipeline on CI/CD infrastructure suffered from build time bloat reaching 4.5 minutes per run. The bottleneck was not syntax testing, but rather the slow dependency resolution cycle of pip/poetry and high RAM consumption when building virtual environments on resource-constrained KVM VPS instances.
When operating microservices on servers with cgroups v2 memory limits (such as a 2-core 4GB RAM VPS), compiling C-extension wheels via pip frequently triggered Out-Of-Memory (OOM) killer events. Concurrently, using pyenv to manage multi-version Python runtimes added unnecessary binary layer complexity and disk I/O overhead.
Architectural Dilemma: Legacy Tooling vs Rust-Based Package Manager
The Python ecosystem has long been fragmented between package managers (pip, pip-tools, Pipenv, Poetry) and runtime managers (pyenv, asdf). At production scale, this fragmentation presents three critical flaws:
-
Slow Lockfile Resolution:
Poetryandpiputilize pure Python backtracking search algorithms. On complex dependency trees (e.g., PyTorch, FastAPI, NumPy, Pydantic v2), resolution takes anywhere from 40 to 120 seconds. -
High RAM Footprint: Calculating dependency graphs via
pipandpoetryconsumes between 800MB and 1.2GB of RAM. On constrained VPS nodes, this triggers OOM panics. - I/O & Disk Footprint Overhead: Every CI/CD runner redundantly downloads and extracts binary tarballs without a secure, system-wide isolated caching layer.
Deep benchmark evaluations of Astral UV (a Rust-based Python package manager) demonstrated massive latency reduction. However, a total migration required rigorous technical analysis before replacing established toolchains.
Comparative Benchmarks & Technical Evaluation
We executed benchmarks on Hostinger KVM VPS infrastructure (2 vCPU, 4GB RAM, NVMe Storage, Ubuntu 24.04 LTS). The testing scenario involved a FastAPI production service containing 48 direct dependencies and 132 transitive dependencies (including C-extensions).
Table 1: Installation Speed, Lockfile Resolution, and RAM Benchmark (Pip vs Poetry vs UV)
| Performance Metric | Legacy (pip + venv) |
Poetry (v1.8.x) |
Astral UV (v0.5.x) | Improvement Margin |
|---|---|---|---|---|
| Cold Build (No Cache) | 84.2 seconds | 68.5 seconds | 4.1 seconds | ~20x Faster |
| Warm Build (Cached) | 32.1 seconds | 19.4 seconds | 0.35 seconds | ~90x Faster |
| Lockfile Resolution (sub-10ms) | N/A (No Lockfile) | 42.1 seconds | 0.008 seconds (8ms) | Sub-10ms Target |
| Peak RAM Consumption | 410 MB | 890 MB | 42 MB | 95% Memory Saved |
| Disk Storage Cache | Redundant (~1.8GB) | Redundant (~1.4GB) | Shared Copy-on-Write (~350MB) | High Disk Efficiency |
| Python Runtime Management | Requires pyenv
|
Requires external python | Native (uv python install) |
Zero External Tools |
The benchmark results prove that Astral UV leverages Rust's multithreading capability and copy-on-write (CoW) filesystem mechanisms to eliminate disk I/O redundancy.
CI/CD Deployment Architecture & Caching Layer
The flowchart below illustrates the integration of UV into the CI/CD deployment pipeline connected to target VPS environments. This setup relies on UV's global content-addressable cache to guarantee sub-second builds.
flowchart TD
A[Developer Push Code] -->|Trigger| B[GitHub Actions Runner]
B --> C{Query UV Global Cache}
C -->|Cache Hit| D[Link Dependencies via Hard-Link]
C -->|Cache Miss| E[Download & Compile via UV Thread Pool]
E --> F[Persist to Global Content-Addressable Storage]
D --> G[Execute Test & Linters]
F --> G
G --> H[Build Production Wheel / Artifact]
H -->|SSH / RSYNC Deployment| I[Hostinger KVM VPS]
I --> J[UV Sync Environment on Target VPS]
J --> K[Reload Uvicorn / Gunicorn Services via Traefik]
In our microservices architecture, this service resides behind a robust Traefik v3 API gateway architecture to handle gRPC and HTTP/3 traffic efficiently.
Declarative Pipeline Configuration (GitHub Actions)
Below is the production-ready GitHub Actions workflow implementation. It leverages uv to manage Python 3.12 and 3.13 runtimes natively without external pyenv dependencies.
name: Production CI/CD Pipeline (UV Powered)
on:
push:
branches: [ main ]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Install Astral UV
uses: astral-sh/setup-uv@v3
with:
enable-cache: true
cache-local-path: "/tmp/.uv-cache"
- name: Set Up Python Multi-Version Runtime
run: |
# UV fetches isolated Python binaries without needing pyenv
uv python install 3.12 3.13
uv venv --python 3.13.venv
- name: Lock & Synchronize Dependencies (Sub-10ms)
run: |
# Sub-10ms lockfile resolution and installation
uv lock
uv sync --frozen --extra production
- name: Run Test Suite
run: |
uv run pytest tests/ --maxfail=1 --disable-warnings
- name: Deploy to KVM VPS via SSH
uses: appleboy/ssh-action@v1.0.0
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USERNAME }}
key: ${{ secrets.VPS_SSH_KEY }}
script: |
cd /var/www/my-python-service
git pull origin main
# Execute UV sync under systemd cgroups memory constraints
systemd-run --scope -p MemoryMax=512M uv sync --frozen --no-dev
sudo systemctl reload my-python-service
Multi-Version Strategy & VPS Resource Optimization
A primary challenge on budget VPS instances (2GB-4GB RAM) is memory spikes during C-extension compilation (pydantic, grpcio, cryptography).
1. Eliminating Pyenv with Native UV Python Management
UV features native uv python execution to download pre-built, optimized Python binaries (standalone builds by Indygreg) on-demand. This eliminates compiling Python from source, saving 15 minutes of CPU-intensive compilation on your target server.
# Install Python 3.13 without root or pyenv
uv python install 3.13.1
# Instantly execute scripts using specific runtime versions
uv run --python 3.13 main.py
2. RAM Overhead Mitigation via Linux cgroups v2
When deploying directly to Hostinger KVM VPS infrastructure, we restrict peak memory usage of uv processes via systemd-run or Docker memory flags. Thanks to Rust's zero-cost abstractions, UV maintains memory usage under 50MB during dependency resolution, staying far below cgroups throttling thresholds (512MB).
Infrastruktur di atas mendukung skalabilitas proses operasional jangka panjang.
Architectural Decision & System Consequences
Decision:
We officially adopt Astral UV (UV Python 2026) as our standardized runtime management, package resolution, and deployment toolchain across all Python services at Bijak Technology.
Positive Consequences:
- CI/CD Speedup: Overall GitHub Actions build execution dropped from 4.5 minutes to 22 seconds (~90% decrease in build latency).
- Server Resource Efficiency: Zero deployment crashes caused by RAM OOM panics on VPS nodes.
-
Toolchain Simplification: Replaced
pip,pip-tools,poetry,virtualenv, andpyenvwith a single, standalone binary executable:uv.
Negative Consequences & Mitigation:
-
Astral Ecosystem Lock-in Risk: Mitigated by UV's strict adherence to standard Python PEPs (PEP 508, PEP 621, PEP 722,
pyproject.toml). Reverting to standardpipcan be achieved without altering application source code.
Transparency: Some links in this article are affiliate links that support our technical research publications at no additional cost to you.
Explore more in-depth system architecture blueprints, FinOps strategies, and enterprise implementations at Bijak Technology.
Top comments (0)