managing-environments

Managing Development Environments

Guidelines for working with Python virtual environments (venv) and conda environments. This skill ensures safe, organized package installations by always checking and confirming the active environment before proceeding.

Supporting files in this directory:

• installation-patterns.md - Installation commands for venv and conda, channel priority, TOS error handling
• best-practices-and-scenarios.md - Common scenarios, best practices, resumable data fetch patterns
• troubleshooting-and-examples.md - Troubleshooting common issues and worked examples

When to Use This Skill

Activate this skill whenever:

• Installing Python packages or tools
• User requests to install dependencies
• Setting up a new Python project
• Debugging import or package issues
• Working with any Python development

Core Principles

1. Always check environment status before any installation
2. Always confirm with user which environment to use
3. Never install without environment confirmation
4. Warn if no environment is active
5. Help user choose appropriate environment type

---

Environment Detection Workflow

Step 1: Check Environment Status

Before ANY installation command, run these checks:

# Check for active venv
echo "Python executable: $(which python)"
echo "Virtual environment: $VIRTUAL_ENV"

# Check for conda environment
echo "Conda environment: $CONDA_DEFAULT_ENV"
conda info --envs 2>/dev/null || echo "Conda not available"

Step 2: Interpret Results

Scenario A: venv is active

Python executable: /path/to/project/.venv/bin/python
Virtual environment: /path/to/project/.venv
Conda environment:

-> Python venv is active

Scenario B: conda environment is active

Python executable: /path/to/miniconda3/envs/myenv/bin/python
Virtual environment:
Conda environment: myenv

-> Conda environment is active

Scenario C: No environment (system Python)

Python executable: /usr/bin/python
Virtual environment:
Conda environment:

-> No environment active! Warn user.

Scenario D: Both detected (rare)

Virtual environment: /path/to/.venv
Conda environment: base

-> Both active, prioritize what which python shows, but confirm with user

Step 3: Confirm with User

Always ask before proceeding:

I've detected the following environment:
- Environment type: [venv/conda/none]
- Location: [path]
- Python version: [version]

Is this the environment you want me to use for installing [package/tool]?

Wait for user confirmation before proceeding.

For installation commands by environment type, see installation-patterns.md.

---

No Environment Active - Warning & Planning

If no environment is detected, DO NOT PROCEED with installation. Instead:

Step 1: Warn User

WARNING: No Python environment detected!

You're currently using system Python:
- Location: [path to python]
- Version: [version]

Installing packages to system Python can:
- Cause conflicts with system packages
- Require sudo/admin privileges
- Make projects difficult to reproduce
- Break system tools that depend on specific versions

I recommend creating a virtual environment first.

Step 2: Help Choose Environment Type

Decision Tree:

Question: What type of project are you working on?

A. Pure Python project (web dev, scripting, etc.)
   -> Recommend: Python venv
   -> Fast, lightweight, standard Python tool

B. Data science / Scientific computing
   -> Ask: Do you need non-Python dependencies? (R, C libraries, etc.)

   B1. Yes (or using packages like numpy, scipy, pandas, etc.)
       -> Recommend: Conda
       -> Better binary dependency management

   B2. No, only Python packages
       -> Recommend: Python venv
       -> Simpler and faster

C. Bioinformatics / Genomics
   -> Recommend: Conda (with bioconda channel)
   -> Most tools available via bioconda
   -> Manages complex dependencies well

D. Galaxy tool development
   -> Recommend: Conda
   -> Galaxy uses conda for tool dependencies
   -> Direct compatibility

Step 3: Offer to Create Environment

For venv:

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
which python

For conda:

conda create -n project-name python=3.11
conda activate project-name
conda info --envs
which python

---

Environment Selection Guidelines

Use Python venv When:

• Pure Python project
• Simple dependencies (all available on PyPI)
• Standard web development (Django, Flask, FastAPI)
• No compiled extensions or C libraries
• Want fastest environment creation
• Working with Python 3.3+

Advantages: Lightweight, fast, built into Python, works on all platforms. Disadvantages: Harder to manage non-Python dependencies, binary packages may need system libraries.

Use Conda Environment When:

• Data science / machine learning
• Scientific computing (numpy, scipy, pandas)
• Bioinformatics / genomics
• Need specific Python versions
• Cross-language dependencies (R, C++, etc.)
• Galaxy tool development
• Complex binary dependencies

Advantages: Manages binary dependencies, cross-language support, better for scientific packages, can manage Python version. Disadvantages: Slower than venv, larger disk space, requires conda installation.

---

Quick Reference

Environment Detection Commands

# Check what's active
which python
echo $VIRTUAL_ENV
echo $CONDA_DEFAULT_ENV

# Python version
python --version

# Installed packages
pip list          # for pip
conda list        # for conda

# Environment location
pip show package-name  # shows where package is installed

Activation Commands

# venv
source .venv/bin/activate                    # Linux/Mac
.venv\Scripts\activate                       # Windows

# conda
conda activate environment-name

# Deactivation
deactivate                                   # venv
conda deactivate                             # conda

For common scenarios, best practices, troubleshooting, and worked examples, see the supporting files in this directory.

---

Summary

Always remember:

1. Check environment before any installation
2. Show user what environment is active
3. Confirm with user before proceeding
4. Warn if no environment is active
5. Help choose appropriate environment type
6. Document environment setup for reproducibility

Never:

• Install without checking environment
• Assume user wants to use system Python
• Install without user confirmation
• Skip warning about base conda environment

This skill ensures clean, reproducible, conflict-free Python environments across all projects.