# Virtual Environment Creation

> Use when before installing ENPKG dependencies for the first time, or when setting up the workflow on a new machine or user account. Trigger when you have cloned enpkg_full or enpkg_workflow and need to install runtime and optional development dependencies in isolation.

- Skill: `holobiomicslab/virtual-environment-creation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/virtual-environment-creation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/virtual-environment-creation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/virtual-environment-creation

---


# virtual-environment-creation

## Summary

Create an isolated Python virtual environment using uv or conda to manage dependencies and avoid conflicts when installing ENPKG workflow components. This ensures reproducible, project-specific package versions without contaminating the system Python installation.

## When to use

Before installing ENPKG dependencies for the first time, or when setting up the workflow on a new machine or user account. Trigger when you have cloned enpkg_full or enpkg_workflow and need to install runtime and optional development dependencies in isolation.

## When NOT to use

- If the ENPKG workflow is already installed and environment is active (re-activation suffices).
- If you are running via a container (Docker, Singularity) that already provides dependency isolation.
- If system-wide Python package management is enforced by institutional policy and project-level isolation is forbidden.

## Inputs

- Project root directory (enpkg_full or enpkg_workflow cloned repository)
- pyproject.toml or requirements file with pinned dependencies
- System with Git and Anaconda/Miniconda or uv pre-installed

## Outputs

- .venv directory (isolated Python virtual environment)
- Activated shell session with environment variables pointing to .venv/bin
- Installed runtime and optional development packages in .venv/lib/pythonX.Y/site-packages

## How to apply

Use the uv package manager (recommended over conda for ENPKG) to create and sync an isolated .venv in the project root by running `uv sync` to install runtime dependencies, or `uv sync --group dev` to include development tools like pytest and linters. If uv is not installed, first install it via the documented curl command. Optionally specify a Python version (e.g., `uv python install 3.11`) before syncing. Activate the environment with `source .venv/bin/activate` on Linux/macOS or use `uv run` as a prefix to execute commands without manual activation. The rationale is that ENPKG calls multiple external tools (MZmine, Sirius, GraphDB connectors) and requires precise version pinning; isolation prevents dependency conflicts and ensures reproducibility across environments.

## Related tools

- **uv** (Primary dependency manager for creating and syncing isolated Python environment with pinned versions) — https://docs.astral.sh/uv/latest/
- **Anaconda / Miniconda** (Alternative package manager and environment creation tool; prerequisite if uv is not used) — https://docs.anaconda.com/free/anaconda/install/index.html
- **Git** (Required to clone enpkg_full and enpkg_workflow repositories before environment setup) — https://github.com/git-guides/install-git

## Examples

```
curl -LsSf https://astral.sh/uv/install.sh | sh && cd enpkg_full && uv python install 3.11 && uv sync --group dev && source .venv/bin/activate
```

## Evaluation signals

- Verify .venv directory exists in project root and contains bin/, lib/, and include/ subdirectories.
- Confirm environment activation succeeds: `source .venv/bin/activate` returns no errors and shell prompt changes to show (enpkg_full) or similar.
- Run `python --version` and `pip list` within activated environment; verify Python version and installed packages match pyproject.toml or requirements.
- Test environment isolation: `which python` should point to .venv/bin/python, not system Python.
- Run provided validation checks (e.g., `uv run pytest` or test suite commands) to confirm all components are correctly configured.

## Limitations

- uv must be installed separately before running `uv sync`; installation requires curl and internet access.
- The .venv directory is not portable across different OS or CPU architectures; re-sync is needed on new machines.
- Optional development dependencies (pytest, linters) are only installed if `--group dev` is explicitly passed; omitting this flag will not include them.
- Environment variables and machine-specific paths (e.g., PATH_TO_SIRIUS, SIRIUS_USERNAME) are not automatically configured by virtual environment creation; users must separately configure .env file and source it before running workflows.

## Evidence

- [readme] We now rely on uv for dependency management. Install it if needed: "We now rely on [uv](https://docs.astral.sh/uv/latest/) for dependency management. Install it if needed (see the [uv docs](https://docs.astral.sh/uv/latest/#installation) for alternative methods)"
- [readme] uv sync creates a .venv in the project root with dependencies: "With uv installed, sync the project dependencies into an isolated `.venv`"
- [readme] Optional dev dependencies included with --group dev flag: "If you also want the development tooling (pytest, linters, etc.), add the dev dependency group: uv sync --group dev"
- [readme] Activate environment or use uv run prefix: "`uv sync` creates a `.venv` in the project root. Activate it with: source .venv/bin/activate. You can also run commands without activating by prefixing them with `uv run`, e.g.: uv run pytest"
- [readme] Prerequisites include Git and Anaconda or Miniconda: "You will need to have [Git](https://github.com/git-guides/install-git) and [Anaconda](https://docs.anaconda.com/free/anaconda/install/index.html) (or [Miniconda](https://docs.conda.io/en/latest/minico"