Schedule a call
Back to Insights

Inside Valanor’s Python Environment

Table of Contents

Onboarding a new engineer or switching machines should not waste hours on package installs, CUDA wheels, and Jupyter kernels. We wanted a single command that bootstraps a lean, reproducible Python stack for data engineering, analytics, and machine learning, whether on CPU or GPU.

That is why we built valanor-python-env, a standardized environment setup centered on uv, Astral’s ultra-fast Python package and project manager. The repository ships tiered stacks (minimal, standard, full), optional GPU frameworks (PyTorch, TensorFlow, JAX), an auto-registered Jupyter kernel, and a generated environment report for auditability.

Problem and premise

Common pain points across teams:

  • Cold starts are slow. Minutes become hours when dependency resolution and wheel builds stack up.
  • Drift is silent. Two laptops with “the same” environment behave differently, until production does too.
  • GPU is fiddly. Correct CUDA wheels and driver mismatches add time and failure modes.

Premise: Standardize the interface with one script, optimize the engine with uv, and make the environment observable with deterministic outputs: requirements.txt and ENVIRONMENT.md.

What we shipped

Fast installs with uv (drop in replacement for pip and virtualenv, with 10 to 100 times speed improvements).

  • Tiered stacks: minimal (lean base), standard (DE and DS workhorse), full (complete DE + ML + DS).
  • Optional GPU frameworks: choose torch, tensorflow, jax, or all; specify CUDA wheels if needed.
  • Jupyter kernel auto-registration for VS Code and JupyterLab.
  • Environment report (ENVIRONMENT.md) with timestamp, tier, GPU settings, and installed versions.

Quick start (90 seconds, no fuss)

Bash
# 1) Make the bootstrap script executable
chmod +x init_env.sh

# 2) Run it (defaults to the 'standard' tier)
./init_env.sh

# 3) Activate the environment
source .venv/bin/activate
# ...and later
deactivate

The script creates a local .venv with uv, installs the default stack, and generates:

  • a requirements.txt for the selected tier
  • an ENVIRONMENT.md documenting the realized environment

Choose your tier

TierUse when you…Notes
minimalneed a lean Python base to layer onfastest spin up
standard*do daily DE or DS work (analysis, notebooks)default
fullwant the complete DE + ML + DS toolboxall add ons

standard is the default invoked by ./init_env.sh.

Examples

Bash
# Minimal stack
./init_env.sh -t minimal

# Full stack with all GPU frameworks (Torch, TF, JAX)
./init_env.sh -t full --gpu all

# Force specific CUDA wheels (for example, Torch cu126)
./init_env.sh --gpu torch --cuda cu126

Traceable environment reports

Each bootstrap emits an ENVIRONMENT.md like this:

Markdown
# Environment Report
Generated: 2025-09-10 11:45:03
- Tier: standard
- GPU Frameworks: torch
- CUDA: cu126

## Installed Packages (excerpt)
- numpy==2.1.0
- pandas==2.2.2
- ...

This provides a transparent audit trail and helps teams prove “works on my machine” means “works everywhere.”

Why we use uv

  • Speed: written in Rust; parallelized resolution and caching make installs fast.
  • Familiarity: uv pip ... mirrors pip commands, so the workflow feels natural.
  • Correctness: uv requires a virtual environment by default, preventing global pollution.

Examples:

Bash
# Create or reuse a venv
uv venv .venv

# Install from a requirements file
uv pip install -r requirements.txt

# Add a package ad hoc
uv pip install polars

# Update project dependencies
uv add fastapi

From environment to services

The repository includes a simple Makefile to simplify development:

Bash
make setup     # bootstrap the environment
make api       # start FastAPI demo app
make jupyter   # launch JupyterLab
make mlflow    # run the MLflow UI
make start-all # start all services
make logs      # view logs
make stop-all  # stop all services

Logs are saved in ./logs and PIDs in ./run.

Design choices that matter

Single interface, composable flags. One script parses tier and GPU options, then orchestrates uv to create the venv, install the selected tier, register a Jupyter kernel, and emit the report.

Tiering by intent, not by size. minimal is a clean base; standard covers daily data workflows; full brings the Python machine learning toolkit. Fork and tune tiers as needed.

GPU is explicit. Request frameworks individually or all at once, and specify CUDA families when needed. If you skip --gpu, CPU only is the default.

Observable by default. Every run emits both requirements.txt and ENVIRONMENT.md, making diffs visible in version control.

CI/CD setup

A minimal GitHub Actions workflow mirrors local usage:

YAML
name: env-ci
on: [push, pull_request]
jobs:
  setup-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Init env
        run: |
          chmod +x init_env.sh
          ./init_env.sh -t standard

      - name: Run tests
        run: |
          source .venv/bin/activate
          pytest -q

Advanced usage

Corporate indexes. Any pip-compatible flags work with uv:

Bash
uv pip install -r requirements.txt \
  --index-url https://pypi.corp.example/simple \
  --trusted-host pypi.corp.example

Custom tiers. Fork and edit tier definitions while maintaining a consistent output format.

Mac and CUDA. On the M series, use CPU wheels. On Linux GPU nodes, pin CUDA wheels --cuda cu126 to match driver standards.

Common commands

Bash
./init_env.sh -t minimal          # lean base
./init_env.sh -t standard         # default
./init_env.sh -t full             # full stack
./init_env.sh --gpu torch         # PyTorch only
./init_env.sh --gpu all           # Torch, TF, JAX
make jupyter                      # start JupyterLab
uv pip install seaborn            # add package
make stop-all                     # clean shutdown

FAQ

What is Valanor’s Python Environment?

Valanor’s Python Environment is a standardized setup built on uv, designed to create fast, reproducible Python stacks for data, analytics, and machine learning. It ensures consistency across machines and projects while reducing setup time.

Why did Valanor choose uv for environment management?

uv is significantly faster and more reliable than traditional tools like pip or conda. It enforces clean virtual environments, resolves dependencies in parallel, and delivers reproducible results that scale across teams.

How does Valanor’s Python Environment improve reproducibility?

Each setup generates a detailed ENVIRONMENT.md file and a requirements.txt for the selected tier. These artifacts capture the exact package versions and configurations used, allowing teams to recreate environments precisely at any point in time.

Can Valanor’s Python Environment be used for GPU workloads?

Yes. The environment supports GPU frameworks, including PyTorch, TensorFlow, and JAX. Teams can enable or disable GPU support based on their hardware, making it flexible for both local development and production workloads.

Who should use Valanor’s Python Environment?

It is designed for engineers, data scientists, and ML practitioners who value speed, consistency, and transparency. Teams adopting Valanor’s approach can standardize workflows, reduce environment drift, and improve deployment reliability.

Takeaway

Most environment managers add complexity. We went the other way: one script, three tiers, optional GPU, and uv doing the heavy lifting. The result is faster onboarding, fewer environment mismatches, and a straightforward, auditable setup.

If your team needs this model integrated into a larger platform or GPU workflow, we can help. We build systems that withstand pressure and deliver results without distractions.

Turn insight into action.

You’ve read our perspective. Now put it to work. Let’s talk about the systems you need and the pressure they have to handle.

Schedule a Call