venvstacks

https://venvstacks.lmstudio.ai/
Admin
venvstacks is a Python tool that packages applications and dependencies into portable, deterministic...
Tokens:16,853
Snippets:234
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Set up Development Environment with pdm

Source: https://venvstacks.lmstudio.ai/development

Install development dependencies using pdm for an editable install of venvstacks.

```bash
$ pdm sync --dev

```

--------------------------------

### Install venvstacks with pipx

Source: https://venvstacks.lmstudio.ai/

Use pipx to install venvstacks for isolated package management. This is the recommended method for installing command-line tools.

```bash
$ pipx install venvstacks

```

--------------------------------

### Install venvstacks with pip

Source: https://venvstacks.lmstudio.ai/

Install venvstacks as a user-level package using pip. This method may make future Python version upgrades more difficult.

```bash
$ pip install --user venvstacks

```

--------------------------------

### Build Documentation with tox

Source: https://venvstacks.lmstudio.ai/development

Build the project's documentation locally using the tox command with the 'docs' environment.

```bash
$ tox -e docs

```

--------------------------------

### venvstacks.cli.main

Source: https://venvstacks.lmstudio.ai/api/cli

Runs the `venvstacks` CLI. If `_args` is not provided, it defaults to using `sys.argv`.

```APIDOC
## venvstacks.cli.main()

### Description
Runs the `venvstacks` CLI. If `_args` is not given, defaults to using `sys.argv`.

### Signature
`venvstacks.cli.main(_args : Sequence[str] | None = None_) -> None`

### Parameters
* `_args` (Sequence[str] | None, optional): A sequence of strings representing the command-line arguments. Defaults to None, which uses `sys.argv`.
```

--------------------------------

### venvstacks.cli.main()

Source: https://venvstacks.lmstudio.ai/api

The main entry point for the venvstacks command-line interface.

```APIDOC
## venvstacks.cli.main()

### Description
This function serves as the primary entry point for the venvstacks command-line interface.

### Signature
`main()`
```

--------------------------------

### Display venvstacks CLI help

Source: https://venvstacks.lmstudio.ai/overview

Use this command to view the available options and commands for the venvstacks CLI.

```bash
$ venvstacks --help

Usage: venvstacks [OPTIONS] COMMAND [ARGS]...

Lock, build, and publish Python virtual environment stacks.

╭─ Options ───────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                     │
╰─────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────╮
│ build          Build (/lock/publish) Python virtual environment stacks.         │
│ local-export   Export layer environments for Python virtual environment stacks. │
│ lock           Lock layer requirements for Python virtual environment stacks.   │
│ publish        Publish layer archives for Python virtual environment stacks.    │
╰─────────────────────────────────────────────────────────────────────────────────╯

```

--------------------------------

### Apple MLX Stack Configuration with Platform Targeting

Source: https://venvstacks.lmstudio.ai/examples

Demonstrates platform-specific targeting for MLX, including OS version locking and conditional dependencies. Shows how irrelevant dependencies are filtered out.

```toml
# Demonstrate using priority indexes to define cross-platform parallel torch stacks
[[runtimes]]
name = "cpython3.11"
python_implementation = "cpython@3.11.13"
requirements = []
platforms = [
    "macosx_arm64",
    "linux_x86_64",
]

[[frameworks]]
name = "mlx"
runtime = "cpython3.11"
linux_target = "glibc@2.35"
macosx_target = "14"
requirements = [
    "mlx==0.29.3",
    "mlx[cpu]; sys_platform == 'linux'",
]
# Platform restrictions are inherited from lower layers

[[frameworks]]
name = "mlx-cuda"
runtime = "cpython3.11"
linux_target = "glibc@2.35"
macosx_target = "14"
requirements = [
    "mlx[cuda]==0.29.3",
]
# A separate CUDA-based layer stack is really only needed on Linux,

```

--------------------------------

### Create Changelog Entry with scriv

Source: https://venvstacks.lmstudio.ai/development

Create a new changelog entry for user-facing changes using the 'scriv create' command.

```bash
scriv create

```

--------------------------------

### Run venvstacks CLI

Source: https://venvstacks.lmstudio.ai/development

Execute the venvstacks command-line interface with the --help option to view available commands and options.

```bash
$ pdm run venvstacks --help

```

--------------------------------

### Publish environment layer archives

Source: https://venvstacks.lmstudio.ai/overview

Converts successfully built environments into separate reproducible binary archives suitable for transferring to another system. Metadata is published alongside artifacts.

```bash
$ venvstacks publish --tag-outputs --output-dir demo_artifacts examples/sklearn/venvstacks.toml

```

--------------------------------

### Configure PyTorch CPU and CUDA Stacks

Source: https://venvstacks.lmstudio.ai/examples

Sets up PyTorch application stacks using different package indexes for CPU and CUDA versions. Includes a combined stack that prioritizes CUDA.

```toml
# Demonstrate using priority indexes to define cross-platform parallel torch stacks
[[runtimes]]
name = "cpython3.11"
python_implementation = "cpython@3.11.13"
requirements = [
    # Share a common numpy across the different torch variants
    "numpy",
]

[[frameworks]]
name = "torch-cpu"
runtime = "cpython3.11"
package_indexes = { torch = "pytorch-cpu" }
# priority_indexes = ["pytorch-cpu"]
requirements = [
    "torch==2.8.0",
    # Skip listing numpy, so numpy updates don't automatically invalidate the layer lock
]
dynlib_exclude = [
    "triton/**"
]
platforms = [
    "linux_aarch64",
    "linux_x86_64",
    "macosx_arm64",
    # "macosx_x86_64",  # PyTorch does not publish wheels for macOS on Intel
    "win_amd64",
    "win_arm64",
]

[[frameworks]]
name = "torch-cu128"
runtime = "cpython3.11"
package_indexes = { torch = "pytorch-cu128" }
# priority_indexes = ["pytorch-cu128"]
requirements = [
    "torch==2.8.0",
    # Skip listing numpy, so numpy updates don't automatically invalidate the layer lock
]
dynlib_exclude = [
    "triton/**"
]
platforms = [
    # "linux_aarch64",  # No wheel available in the PyTorch 2.8.0 CUDA repo
    "linux_x86_64",
    # "macosx_arm64",  # CUDA is not used on macOS
    # "macosx_x86_64",  # PyTorch does not publish wheels for macOS on Intel
    "win_amd64",
    # "win_arm64",  # No wheel available in the PyTorch 2.8.0 CUDA repo
]

[[applications]]
name = "cpu"
launch_module = "report_torch_cuda_version.py"
frameworks = ["torch-cpu"]
requirements = [
    # Exact version pin is inherited from the framework layer
    "torch",
]

[[applications]]
name = "cu128"
launch_module = "report_torch_cuda_version.py"
frameworks = ["torch-cu128"]
requirements = [
    # Exact version pin is inherited from the framework layer
    "torch",
]

[[applications]]
name = "cu128-or-cpu"
launch_module = "report_torch_cuda_version.py"
# Both the CUDA and non-CUDA frameworks are added to the import path,
# so this app will work as long as *either* of those layers is installed
# If both are available, it uses the CUDA layer (as it is listed first)
# However, the layer locking needs to be told that it is expected that
# the two layers specify different source indexes, and given a conflict,
# the pytorch-cu128 index should be used in preference to pytorch-cpu
index_overrides = { pytorch-cpu = "pytorch-cu128" }
frameworks = ["torch-cu128", "torch-cpu"]
requirements = [
    # Exact version pin is inherited from the framework layer
    "torch",
]


[tool.uv]
# exclude-newer = "2025-10-11T00:00:00Z"
# The custom torch registries do not support exclude-newer,
# and that currently requires avoiding the feature entirely
```

--------------------------------

### Build Process Configuration

Source: https://venvstacks.lmstudio.ai/api/stacks

Configuration options for the build process, specifically for package index access.

```APIDOC
## Build Process Configuration

### `PackageIndexConfig`

Python package index access configuration.
```

--------------------------------

### venvstacks.pack_venv.create_archive()

Source: https://venvstacks.lmstudio.ai/api

Creates a compressed archive of a virtual environment.

```APIDOC
## venvstacks.pack_venv.create_archive()

### Description
Generates a compressed archive (e.g., tar.gz) of the specified virtual environment, suitable for distribution or backup.

### Signature
`create_archive(venv_path: str, output_path: str)`

### Parameters
#### Path Parameters
- **venv_path** (str) - Required - The path to the virtual environment to archive.
- **output_path** (str) - Required - The path where the archive file will be saved.
```

--------------------------------

### Run Code Formatting with tox

Source: https://venvstacks.lmstudio.ai/development

Execute code formatting checks using tox with the 'format' environment.

```bash
$ tox -e format

```

--------------------------------

### Scikit-learn Stack Configuration

Source: https://venvstacks.lmstudio.ai/examples

Defines runtimes, frameworks (scikit-learn and GUI), and applications for classification and clustering demos. Includes platform-specific requirements and tool configuration.

```toml
[[runtimes]]
name = "cpython-3.11"
python_implementation = "cpython@3.11.10"
requirements = [
    "numpy",
    "matplotlib",
]

[[frameworks]]
name = "sklearn"
runtime = "cpython-3.11"
requirements = [
    "scikit-learn",
]
platforms = [
    "linux_aarch64",
    "linux_x86_64",
    "macosx_arm64",
    "macosx_x86_64",
    "win_amd64",
    # "win_arm64",  # No wheel available on PyPI
]

[[frameworks]]
# Use a non-default GUI due to problems with Tcl/Tk in python-build-standalone:
# https://github.com/astral-sh/uv/issues/6893
name = "gui"
runtime = "cpython-3.11"
linux_target = "glibc@2.34"
requirements = [
    "pyside6",
]
platforms = [
    # "linux_aarch64",  # No wheel available on PyPI
    "linux_x86_64",
    "macosx_arm64",
    "macosx_x86_64",
    "win_amd64",
    "win_arm64",
]



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

[[applications]]
name = "clustering-demo"
launch_module = "launch_modules/sklearn_clustering.py"
frameworks = ["sklearn", "gui"]
requirements = [
    "scikit-learn",
    "matplotlib",
    "pyside6",
]

[tool.uv]
exclude-newer = "2025-10-11T00:00:00Z"

```

--------------------------------

### venvstacks.pack_venv.create_archive

Source: https://venvstacks.lmstudio.ai/api/pack_venv

shutil.make_archive replacement, tailored for Python virtual environments. It injects a suitable `postinstall.py` script, always creates zipfile archives on Windows and xztar archives elsewhere, excludes `__pycache__` and `sitecustomize.py` files, replaces symlinks with copies on Windows, discards tar entry owner/group info, clears tar entry high mode bits and group/other write mode bits, clamps mtime of archived files, and shows progress reporting by default.

```APIDOC
## venvstacks.pack_venv.create_archive

### Description
shutil.make_archive replacement, tailored for Python virtual environments. It injects a suitable `postinstall.py` script, always creates zipfile archives on Windows and xztar archives elsewhere, excludes `__pycache__` and `sitecustomize.py` files, replaces symlinks with copies on Windows, discards tar entry owner/group info, clears tar entry high mode bits and group/other write mode bits, clamps mtime of archived files, and shows progress reporting by default.

Set _work_dir_ if `/tmp` is too small for archiving tasks.

### Parameters
#### Path Parameters
- **_source_dir** (str | PathLike[str]) - Required - The source directory of the virtual environment.
- **_archive_base_name** (str | PathLike[str]) - Required - The base name for the archive file.
- **_install_target** (str | None) - Optional - The target directory for installation.
- **_clamp_mtime** (datetime | None) - Optional - The maximum mtime for archived files.
- **_work_dir** (str | PathLike[str] | None) - Optional - The working directory for archiving tasks.
- **_show_progress** (bool) - Optional - Whether to show progress reporting (default: True).
- **_format** (CompressionFormat | None) - Optional - The compression format for the archive.
- **_prepare_deployed_env** (Callable[[Path], None] | None) - Optional - A callable to prepare the deployed environment.

### Returns
Path - The path to the created archive.
```

--------------------------------

### Run Tests with Labeled Environments using Tox

Source: https://venvstacks.lmstudio.ai/development

Run tests using predefined labels for the oldest, latest, or all test environments.

```bash
$ tox -m test_oldest

```

```bash
$ tox -m test_latest

```

```bash
$ tox -m test_all

```

--------------------------------

### Configure uv for PyTorch CPU Wheels

Source: https://venvstacks.lmstudio.ai/examples

This configuration snippet sets up uv to use a specific index URL for PyTorch CPU wheels. Ensure this configuration is placed within your project's tool configuration file.

```toml
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu/"
explicit = true
```

--------------------------------

### Run Linting Checks with tox

Source: https://venvstacks.lmstudio.ai/development

Execute code linting checks using tox with the 'lint' environment.

```bash
$ tox -e lint

```

--------------------------------

### Layer Build Environments

Source: https://venvstacks.lmstudio.ai/api/stacks

Base classes and specific implementations for building layer environments.

```APIDOC
## Layer Build Environments

### `LayerEnvBase`

Common base class for layer build environment implementations.

### `RuntimeEnv`

Base runtime layer build environment.

### `LayeredEnvBase`

Common base class for framework and application layer build environments.

### `FrameworkEnv`

Framework layer build environment.

### `ApplicationEnv`

Application layer build environment.

### `EnvironmentLock`

Layered environment dependency locking management.

### `EnvironmentLockMetadata`

Details of the last time this environment was locked.
```

--------------------------------

### Runtime and Implementation Metadata Fields

Source: https://venvstacks.lmstudio.ai/file-formats

Describes metadata fields populated after initial layer definition, indicating runtime dependencies and implementation details.

```yaml
# Fields that are populated after the layer metadata has initially been defined
# "runtime_layer" is set to the underlying runtime's deployed environment name
# "python_implementation" is set to the underlying runtime's implementation name
# "bound_to_implementation" means that the layered environment includes
# copies of some files from the runtime implementation, and hence will
# need updating even for runtime maintenance releases
runtime_layer: NotRequired[str]
python_implementation: NotRequired[str]
bound_to_implementation: NotRequired[bool]
```

--------------------------------

### Build environment stack

Source: https://venvstacks.lmstudio.ai/overview

Converts layer specifications and their locked requirements into a working Python environment. If not explicitly locked, it will lock them as necessary.

```bash
$ venvstacks build examples/sklearn/venvstacks.toml

```

--------------------------------

### venvstacks.pack_venv.convert_symlinks()

Source: https://venvstacks.lmstudio.ai/api

Converts symbolic links within a virtual environment to regular files.

```APIDOC
## venvstacks.pack_venv.convert_symlinks()

### Description
Converts symbolic links within a virtual environment into regular files, which is often necessary for packaging or archiving.

### Signature
`convert_symlinks(venv_path: str)`

### Parameters
#### Path Parameters
- **venv_path** (str) - Required - The path to the virtual environment.
```

--------------------------------

### Export Environment Stack Locally

Source: https://venvstacks.lmstudio.ai/overview

Use this command to copy built environments to a different location on the same system, applying filtering steps similar to archive packing. This is useful for iterating on layer definitions and launch module details without the overhead of packing and unpacking archives.

```bash
$ venvstacks local-export --output-dir demo_export examples/sklearn/venvstacks.toml

```

--------------------------------

### venvstacks.pack_venv.export_venv

Source: https://venvstacks.lmstudio.ai/api/pack_venv

Export the given build environment, skipping archive creation and unpacking. It injects a suitable `postinstall.py` script, excludes `__pycache__` and hidden files, replaces symlinks with copies on Windows or if the target doesn't support symlinks. If supplied, `_run_postinstall` is called with the path to the environment’s Python interpreter and its postinstall script, allowing execution by the calling application.

```APIDOC
## venvstacks.pack_venv.export_venv

### Description
Export the given build environment, skipping archive creation and unpacking. It injects a suitable `postinstall.py` script, excludes `__pycache__` and hidden files, replaces symlinks with copies on Windows or if the target doesn’t support symlinks.

If supplied, _run_postinstall_ is called with the path to the environment’s Python interpreter and its postinstall script, allowing execution of the post-install script by the calling application. The post-install script is NOT implicitly executed by the export process.

### Parameters
#### Path Parameters
- **_source_dir** (str | PathLike[str]) - Required - The source directory of the virtual environment.
- **_target_dir** (str | PathLike[str]) - Required - The target directory for the exported environment.
- **_prepare_deployed_env** (Callable[[Path], None] | None) - Optional - A callable to prepare the deployed environment.
- **_run_postinstall** (Callable[[Path, Path], None] | None) - Optional - A callable to run the post-install script.

### Returns
Path - The path to the exported environment.
```

--------------------------------

### Run Type Checking with tox

Source: https://venvstacks.lmstudio.ai/development

Execute static type checking using tox with the 'typecheck' environment.

```bash
$ tox -e typecheck

```

--------------------------------

### JupyterLab Stack Configuration

Source: https://venvstacks.lmstudio.ai/examples

Defines a minimal stack with a runtime and a single application for JupyterLab. Includes platform restrictions and tool configuration.

```toml
[[runtimes]]
name = "cpython3.11"
python_implementation = "cpython@3.11.13"
requirements = []

[[applications]]
# No framework layers in the initial version of the example
name = "jupyterlab"
launch_module = "run_jupyterlab.py"
runtime = "cpython3.11"
requirements = ["jupyterlab"]

platforms = [
    "linux_aarch64",
    "linux_x86_64",
    "macosx_arm64",
    "macosx_x86_64",
    "win_amd64",
    # "win_amd64",  # No public pyyaml wheel available
]

[tool.uv]
exclude-newer = "2025-10-11T00:00:00Z"

```

--------------------------------

### Configure uv for PyTorch CUDA 12.8 Wheels

Source: https://venvstacks.lmstudio.ai/examples

This configuration snippet sets up uv to use a specific index URL for PyTorch wheels compatible with CUDA 12.8. Ensure this configuration is placed within your project's tool configuration file.

```toml
[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128/"
explicit = true
```

--------------------------------

### Configure MLX Application Stack

Source: https://venvstacks.lmstudio.ai/examples

Defines application stacks for MLX, specifying requirements and platform compatibility. Filters unused dependencies for specific platforms.

```toml
[[applications]]
name = "mlx-example"
launch_module = "report_mlx_version.py"
frameworks = ["mlx"]
requirements = [
    # Exact version pin is inherited from the framework layer
    "mlx",
]
# Platform restrictions are inherited from lower layers

[[applications]]
name = "mlx-cuda-linux"
launch_module = "report_mlx_version.py"
frameworks = ["mlx-cuda"]
requirements = [
    # Exact version pin is inherited from the framework layer
    "mlx[cuda]",
]
# macos-only dependencies should be omitted from the layer summary
platforms = [
    "linux_x86_64",
]

[[applications]]
name = "mlx-cuda-macos"
launch_module = "report_mlx_version.py"
frameworks = ["mlx-cuda"]
requirements = [
    # Exact version pin is inherited from the framework layer
    "mlx[cuda]",
]
# Linux-only dependencies should be omitted from the layer summary
platforms = [
    "macosx_arm64",
]

[tool.uv]
exclude-newer = "2025-10-19T00:00:00Z"
# Only resolve for the relevant target platforms
environments = [
    "sys_platform == 'darwin' and platform_machine == 'arm64'",
    "sys_platform == 'linux' and platform_machine == 'x86_64'",
]
# required-environments is intentionally NOT set,
# as not all layers are built for all platforms
```

--------------------------------

### venvstacks.pack_venv.export_venv()

Source: https://venvstacks.lmstudio.ai/api

Exports a virtual environment to a specified directory.

```APIDOC
## venvstacks.pack_venv.export_venv()

### Description
Exports the contents of a virtual environment to a target directory, potentially including metadata and configuration.

### Signature
`export_venv(venv_path: str, export_path: str)`

### Parameters
#### Path Parameters
- **venv_path** (str) - Required - The path to the virtual environment to export.
- **export_path** (str) - Required - The directory where the virtual environment will be exported.
```

--------------------------------

### High Level Interface

Source: https://venvstacks.lmstudio.ai/api/stacks

These are the primary interfaces for interacting with the venvstacks environment stack creation and building process.

```APIDOC
## High Level Interface

### `StackSpec`

Layered environment stack specification.

### `BuildEnvironment`

Interface to build specified layered environment stacks.
```

--------------------------------

### Configure Private Index Server

Source: https://venvstacks.lmstudio.ai/source-builds

Configure venvstacks to use a private index server for package resolution. This is useful for serving both cached public packages and privately built artifacts.

```toml
[[tool.uv.index]]
url = "https://internal.example.com/pyindex/"
default = true

```

--------------------------------

### venvstacks.pack_venv.get_archive_path

Source: https://venvstacks.lmstudio.ai/api/pack_venv

Report the name of the archive that will be created for the given base name.

```APIDOC
## venvstacks.pack_venv.get_archive_path

### Description
Report the name of the archive that will be created for the given base name.

### Parameters
#### Path Parameters
- **_archive_base_name** (str | PathLike[str]) - Required - The base name for the archive file.

### Returns
Path - The path to the archive file.
```

--------------------------------

### Application Environment Metadata Fields

Source: https://venvstacks.lmstudio.ai/file-formats

Specifies additional metadata fields exclusively for application environments, including launch module information.

```yaml
# Extra fields only defined for application environments
app_launch_module: NotRequired[str]
app_launch_module_hash: NotRequired[str]
```

--------------------------------

### Layer Specifications

Source: https://venvstacks.lmstudio.ai/api/stacks

Base classes and specific types for defining layer specifications within an environment stack.

```APIDOC
## Layer Specifications

### `LayerSpecBase`

Common base class for layer environment specifications.

### `RuntimeSpec`

Base runtime layer specification.

### `LayeredSpecBase`

Common base class for framework and application layer specifications.

### `FrameworkSpec`

Framework layer specification.

### `ApplicationSpec`

Application layer specification.
```

--------------------------------

### Run Slow Tests with Tox

Source: https://venvstacks.lmstudio.ai/development

Execute only the slow tests using tox by specifying the 'slow' marker. This command targets the default testing environment.

```bash
$ tox -m test -- -m "slow"

```

--------------------------------

### venvstacks.pack_venv.convert_symlinks

Source: https://venvstacks.lmstudio.ai/api/pack_venv

Make env portable by making internal symlinks relative and external links hard. If set, containing path must be a parent directory of the environment path and is used as the boundary for creating relative symlinks instead of hard links. If not set, the environment path itself is used as the boundary for creating relative symlinks. Returns a 2-tuple containing lists of internal relative link conversions and external hard link conversions. Each list contains source/target Path pairs.

```APIDOC
## venvstacks.pack_venv.convert_symlinks

### Description
Make env portable by making internal symlinks relative and external links hard. If set, containing path must be a parent directory of the environment path and is used as the boundary for creating relative symlinks instead of hard links. If not set, the environment path itself is used as the boundary for creating relative symlinks.

### Parameters
#### Path Parameters
- **_env_dir** (str | PathLike[str]) - Required - The path to the virtual environment directory.
- **_containing_dir** (str | PathLike[str] | None) - Optional - A parent directory of the environment path used as the boundary for creating relative symlinks.

### Returns
tuple[list[tuple[Path, Path]], list[tuple[Path, Path]]] - A 2-tuple containing lists of internal relative link conversions and external hard link conversions. Each list contains source/target Path pairs.
```

--------------------------------

### Clone venvstacks Repository

Source: https://venvstacks.lmstudio.ai/development

Clone the venvstacks source code from GitHub and navigate into the project directory.

```bash
$ git clone https://github.com/lmstudio-ai/venvstacks
$ cd venvstacks

```

--------------------------------

### venvstacks.pack_venv.get_archive_path()

Source: https://venvstacks.lmstudio.ai/api

Determines the expected archive path for a virtual environment.

```APIDOC
## venvstacks.pack_venv.get_archive_path()

### Description
Calculates and returns the standard or expected file path for an archive of a given virtual environment, based on naming conventions.

### Signature
`get_archive_path(venv_path: str) -> str`

### Parameters
#### Path Parameters
- **venv_path** (str) - Required - The path to the virtual environment.

### Returns
- **str** - The calculated path for the virtual environment's archive.
```

--------------------------------

### Framework and Application Layer Metadata Fields

Source: https://venvstacks.lmstudio.ai/file-formats

Details extra metadata fields specific to framework and application environments, such as required layers.

```yaml
# Extra fields only defined for framework and application environments
required_layers: NotRequired[Sequence[EnvNameDeploy]]
```

--------------------------------

### Show environment stack status

Source: https://venvstacks.lmstudio.ai/overview

Displays the current status of layers in an environment stack. Use --include to filter the displayed tree.

```bash
$ venvstacks show examples/sklearn/venvstacks.toml
/absolute/path/to/examples/sklearn/venvstacks.toml
├── Runtimes
│   └── cpython-3.11
├── Frameworks
│   ├── framework-sklearn
│   │   └── cpython-3.11
│   └── framework-gui
│       └── cpython-3.11
└── Applications
   ├── app-classification-demo
   │   ├── framework-sklearn
   │   ├── framework-gui
   │   └── cpython-3.11
   └── app-clustering-demo
      ├── framework-sklearn
      ├── framework-gui
      └── cpython-3.11

```

```bash
$ pdm run venvstacks show --include 'app-cluster*' examples/sklearn/venvstacks.toml
/home/acoghlan/devel/venvstacks/examples/sklearn/venvstacks.toml
├── Runtimes
│   └── cpython-3.11
├── Frameworks
│   ├── framework-sklearn
│   │   └── cpython-3.11
│   └── framework-gui
│       └── cpython-3.11
└── Applications
   └── app-clustering-demo
      ├── framework-sklearn
      ├── framework-gui
      └── cpython-3.11

```

--------------------------------

### Update Locked CI Dependencies with PDM

Source: https://venvstacks.lmstudio.ai/development

Run the lock_dev_venv.sh script to update pdm's lockfile and export flat constraints files for CI dependencies.

```bash
./lock_dev_venv.sh

```

--------------------------------

### Run Tests with Specific Python Version using Tox

Source: https://venvstacks.lmstudio.ai/development

Execute tests against a specific Python version environment defined in tox.ini, such as py3.11.

```bash
$ tox -e py3.11

```

--------------------------------

### Exceptions

Source: https://venvstacks.lmstudio.ai/api/stacks

Custom exceptions raised by the venvstacks environment management system.

```APIDOC
## Exceptions

### `BuildEnvError`

Raised when a build environment doesn't comply with process restrictions.

### `EnvStackError`

Common base class for all errors specific to managing environment stacks.

### `LayerSpecError`

Raised when an internal inconsistency is found in a layer specification.
```

--------------------------------

### Run Pytest Tests with Tox and Custom Arguments

Source: https://venvstacks.lmstudio.ai/development

Forward custom arguments to pytest via tox, allowing for flexible test selection using file names, markers, or keyword search. Note that default filtering like '-m "not slow"' is replaced and must be re-specified if needed.

```bash
$ tox -m test -- tests/test_basics.py

```

```bash
$ tox -m test -- -m "slow"

```

```bash
$ tox -m test -- -k "lock and not publish"

```

--------------------------------

### Lock environment stack dependencies

Source: https://venvstacks.lmstudio.ai/overview

Performs a complete combined resolution of all environment stacks to ensure layers can be published separately but work together.

```bash
$ venvstacks lock examples/sklearn/venvstacks.toml

```

--------------------------------

### Common Published Layer Metadata Fields

Source: https://venvstacks.lmstudio.ai/file-formats

Lists common metadata fields for published layer archives and exported environments, including names, hashes, and versioning.

```yaml
# Common fields defined for all layers, whether archived or exported
layer_name: EnvNameBuild       # Prefixed layer name without lock version info
install_target: EnvNameDeploy  # Target installation folder when unpacked
requirements_hash: str         # Uses "algorithm:hexdigest" format
lock_version: int              # Monotonically increasing version identifier
locked_at: str                 # ISO formatted date/time value
```

--------------------------------

### Layer Metadata Components

Source: https://venvstacks.lmstudio.ai/api/stacks

Components related to metadata for environment layers, including categories, specifications, and target platforms.

```APIDOC
## Layer Metadata Components

### `LayerCategories`

alias of `LayerCategory`

### `LayerCategory`

Enum for defined layer categories (collections of each variant).

### `LayerSpecMetadata`

Details of a defined environment layer.

### `LayerVariant`

Enum for defined layer variants.

### `LayerVariants`

alias of `LayerVariant`

### `TargetPlatform`

Enum for supported target deployment platforms.

### `TargetPlatforms`

alias of `TargetPlatform`
```

--------------------------------

### Handle Dynamic Library Conflicts in venvstacks

Source: https://venvstacks.lmstudio.ai/design

When dynamic libraries with the same name exist in multiple packages within the same layer, venvstacks reports an exception. Use `dynlib_exclude` to resolve conflicts by specifying patterns for libraries to omit from symlinking.

```python
BuildEnvError: Layer framework-torchvision: './framework-torchvision/share/venv/dynlib/libpng16.16.dylib' already exists, but links to './framework-torchvision/lib/python3.11/site-packages/torchvision/.dylibs/libpng16.16.dylib', not './framework-torchvision/lib/python3.11/site-packages/PIL/.dylibs/libpng16.16.dylib'. Set `dynlib_exclude` in the layer definition to resolve this conflict.
```

```python
dynlib_exclude=["libpng16.*"]
```

```python
dynlib_exclude=["PIL/**/libpng16.*"]
```

```python
dynlib_exclude=["*"]
```
Tokens:
Raw