venvstacks

venvstacks

Task Objectives

• This Skill is used to: master venvstacks layered Python virtual environment packaging and release technology
• Capabilities include: three-layer environment architecture definition, dependency locking, environment building, local export, archive publishing
• Trigger conditions: when users need to package Python ML/AI applications and independently distribute the runtime environment

Prerequisites

• Environment installation:

  pipx install venvstacks
  # 或
  pip install --user venvstacks
  

• Dependency requirement: uv>=0.5.0

Operation Steps

Standard Process

1. Define the environment stack (venvstacks.toml)

[[runtimes]]
name = "cpython@3.11"
fully_versioned_name = "cpython@3.11.10"
requirements = [
    "numpy",
]

[[frameworks]]
name = "sklearn"
runtime = "cpython@3.11"
requirements = [
    "scikit-learn",
]

[[applications]]
name = "classification-demo"
launch_module = "launch_modules/sklearn_classification.py"
frameworks = ["sklearn"]
requirements = [
    "scikit-learn",
]

2. Lock layer dependencies

venvstacks lock sklearn_demo/venvstacks.toml

• Generate the requirements folder
• Use the pylock.toml format to store locked dependencies
• Generate layer lock metadata files

3. Build the environment stack

venvstacks build sklearn_demo/venvstacks.toml

• Create the venv environment
• Install specified packages
• Inject sitecustomize.py to implement layer linking
• Inject the postinstall.py environment configuration script

4. Local export (quick testing)

venvstacks local-export --output-dir demo_export sklearn_demo/venvstacks.toml

• Copy the environment to the specified directory
• Execute postinstall.py

5. Publish archive

venvstacks publish --tag-outputs --output-dir demo_artifacts sklearn_demo/venvstacks.toml

• Generate reproducible binary archives
• Generate metadata files

Optional Branches

When a complete pipeline is needed

# 一步完成锁定、构建、发布
venvstacks build --publish --tag-outputs --output-dir artifacts stack.toml

When multi-platform support is needed

# 锁定（跨平台）
venvstacks lock stack.toml

# 分平台构建
venvstacks build --target linux-x64 stack.toml
venvstacks build --target win32-x64 stack.toml
venvstacks build --target darwin-arm64 stack.toml

# 发布
venvstacks publish --tag-outputs --output-dir artifacts stack.toml

Resource Index

Required Scripts

None (mainly CLI tools)

Domain References

• references/architecture.md

  • When to read: when you need to understand the three-layer architecture
  • Content: detailed explanation of the Runtime, Framework, and Application layers

• references/stack-definition.md

  • When to read: when you need to write venvstacks.toml
  • Content: TOML configuration format, layer definition specifications

• references/cli-commands.md

  • When to read: when you need to understand CLI usage
  • Content: detailed explanation of lock, build, publish, local-export

Notes

Three-Layer Architecture

• Runtime: Python interpreter environment
• Framework: shared frameworks (such as PyTorch, scikit-learn)
• Application: independent application components

Dependency Locking

• Use uv for joint dependency resolution
• Cross-platform locking (pylock.toml format)
• Only allow installation from binary packages

sitecustomize.py

• Implement dependency sharing between layers
• Allow code to import modules from lower-layer packages

Reproducible Builds

• The same input produces byte-identical archives
• Record complete input hashes and output hashes