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

Always check environment status before any installation
Always confirm with user which environment to use
Never install without environment confirmation
Warn if no environment is active
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:

Check environment before any installation
Show user what environment is active
Confirm with user before proceeding
Warn if no environment is active
Help choose appropriate environment type
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.

managing-environments