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 |
- Cold Build (No Cache) β Legacy (pip + venv): 84.2 seconds | Poetry (v1.8.x): 68.5 seconds | Astral UV (v0.5.x): 4.1 seconds | Improvement Margin: ~20x Faster
- Warm Build (Cached) β Legacy (pip + venv): 32.1 seconds | Poetry (v1.8.x): 19.4 seconds | Astral UV (v0.5.x): 0.35 seconds | Improvement Margin: ~90x Faster
- Lockfile Resolution (sub-10ms) β Legacy (pip + venv): N/A (No Lockfile) | Poetry (v1.8.x): 42.1 seconds | Astral UV (v0.5.x): 0.008 seconds (8ms) | Improvement Margin: Sub-10ms Target
- Peak RAM Consumption β Legacy (pip + venv): 410 MB | Poetry (v1.8.x): 890 MB | Astral UV (v0.5.x): 42 MB | Improvement Margin: 95% Memory Saved
- Disk Storage Cache β Legacy (pip + venv): Redundant (~1.8GB) | Poetry (v1.8.x): Redundant (~1.4GB) | Astral UV (v0.5.x): Shared Copy-on-Write (~350MB) | Improvement Margin: High Disk Efficiency
- Python Runtime Management β Legacy (pip + venv): Requires pyenv | Poetry (v1.8.x): Requires external python | Astral UV (v0.5.x): Native (uv python install) | Improvement Margin: 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.


Social Media Share
Copy text or open your social media directly
1/3 Struggling with slow Python builds on your KVM VPS? You are likely facing a dependency resolution bottleneck.
2/3 I've benchmarked the performance of Astral UV vs traditional tools. The results are clear for memory-constrained environments.
3/3 See the full benchmark matrix and architectural guide here: https://bijaktechnology.com/en/blog/uv-python-optimasi-cicd-build-vps/ #Python #DevOps
π‘ How to publish cleanly on Medium.com: