Python Environment Activation

Before running Python-related commands, check if an environment is configured and activate it.

Configuration

Check the project's CLAUDE.md for a "Python Environment" section. It should contain the complete, working activation command:

## Python Environment
```bash
source ~/miniconda3/etc/profile.d/conda.sh && conda run -n myenv <command>

## Running Commands

When running Python commands (python, pip, pytest, mypy, ruff, black, isort, jupyter, jlpm, etc.):

1. Check project's CLAUDE.md for "Python Environment" section
2. If configured, use the **exact saved command pattern**, replacing `<command>` with the actual command
3. If not configured, follow the Setup flow below

## Setup (No Config Found)

If the project's CLAUDE.md has no "Python Environment" section:

1. **Detect available environment managers** - Check what's installed on the system:
   - Use `which` to find tools in PATH (conda, mamba, micromamba, pixi)
   - Check common installation locations (see **Common Installation Locations** below)

2. **ALWAYS ask which environment manager to use**: Use AskUserQuestion
   - Question: "Which environment manager do you use?"
   - **Only show options that were detected as available** (plus "none")
   - **You MUST ask even if only one manager is found**

3. **If "none" selected**: Skip environment setup, run commands directly

4. **List available environments** using the selected manager and patterns from the **Activation Patterns** section below

5. **ALWAYS ask which environment to use**: Use AskUserQuestion
   - **You MUST ask even if an environment name matches the project folder**
   - Show environments that match or relate to the project folder name first
   - Include envs from ALL installations found by that manager
   - Add "Create new environment" option

6. **If "Create new" selected**: Create environment with the selected manager

7. **Test the activation** - Try running a simple command (e.g., `python --version`) with the activation pattern from the **Activation Patterns** section below

8. **CRITICAL - Save the COMPLETE working command to project CLAUDE.md**:
   
   Save the **exact command that successfully ran**, including ALL parts:
   - Shell hook or source command (if needed)
   - Full environment path (not just name if path was required)
   - The run command pattern
   
   **Good example** (saves complete working command):
   ```markdown
   ## Python Environment
   ```bash
   source ~/miniconda3/etc/profile.d/conda.sh && conda run -p /opt/homebrew/Cellar/micromamba/2.4.0/envs/myproject <command>

**Bad example** (incomplete, may not work in fresh shell):
```markdown
## Python Environment
Use `conda run -p /opt/homebrew/Cellar/micromamba/2.4.0/envs/myproject` for Python commands.

The saved command must be copy-paste reproducible in a fresh, non-interactive shell.

9. Run the original command using the saved pattern

Commands to Wrap

These commands need environment activation:

• python, python3
• pip, pip3
• pytest, py.test, tox, nox
• mypy, ruff, black, isort, flake8, pylint
• jupyter, ipython, jlpm
• poetry, pdm, hatch, flit
• pre-commit
• uvicorn, gunicorn, flask, django-admin, celery

Activation Patterns

Always save the FULL working command including any required shell hooks.

Conda

Bash (using profile.d script — works in non-interactive shells):

source <conda_prefix>/etc/profile.d/conda.sh && conda activate <env> && <command>

Bash (using shell hook):

eval "$(conda shell.bash hook)" && conda activate <env> && <command>

Zsh:

eval "$(conda shell.zsh hook)" && conda activate <env> && <command>

Mamba

Bash:

eval "$(mamba shell hook --shell bash)" && mamba activate <env> && <command>

Bash with explicit path (macOS Homebrew):

eval "$(/opt/homebrew/bin/mamba shell hook --shell bash)" && mamba activate <env> && <command>

Zsh:

eval "$(mamba shell hook --shell zsh)" && mamba activate <env> && <command>

Fallback — using conda's hook with mamba (if

mamba shell hook

fails):

eval "$(conda shell.bash hook)" && mamba activate <env> && <command>

Micromamba

Bash:

eval "$(micromamba shell hook --shell bash)" && micromamba activate <env> && <command>

Zsh:

eval "$(micromamba shell hook --shell zsh)" && micromamba activate <env> && <command>

Pixi

Run command directly (preferred):

pixi run <command>

With specific environment:

pixi run -e <environment> <command>

Shell hook for activation (Bash):

cd <project_dir> && eval "$(pixi shell-hook --shell bash)" && <command>

Shell hook for activation (Zsh):

cd <project_dir> && eval "$(pixi shell-hook --shell zsh)" && <command>

Common Installation Locations

macOS:

• ~/miniconda3/

• ~/anaconda3/

• ~/miniforge3/

• ~/mambaforge/

• /opt/homebrew/Caskroom/miniconda/base/

• /usr/local/Caskroom/miniconda/base/

Linux:

• ~/miniconda3/

• ~/anaconda3/

• ~/miniforge3/

• ~/mambaforge/

• /opt/conda/

• /opt/miniconda3/

• /usr/local/miniconda3/

• /home/<user>/anaconda3/

Micromamba:

• ~/.local/bin/micromamba

• /opt/homebrew/bin/micromamba

• /usr/local/bin/micromamba

• ~/bin/micromamba

Finding the Tool Path

If the tool isn't in PATH, find it:

which conda
which mamba
which micromamba
which pixi

Or check common locations:

# macOS Homebrew
ls /opt/homebrew/bin/{mamba,micromamba,conda,pixi} 2>/dev/null
ls /usr/local/bin/{mamba,micromamba,conda,pixi} 2>/dev/null

# User installations
ls ~/miniconda3/bin/conda 2>/dev/null
ls ~/miniforge3/bin/mamba 2>/dev/null
ls ~/mambaforge/bin/mamba 2>/dev/null
ls ~/.local/bin/micromamba 2>/dev/null
ls ~/.pixi/bin/pixi 2>/dev/null

If Activation Fails

If a saved command stops working:

1. Re-test with a simple command like

   python --version

2. Try different activation patterns from the Activation Patterns section above
3. Once working, update CLAUDE.md with the new complete command

Common issues:

• "CommandNotFoundError: Your shell has not been properly configured" — Run

  conda init <shell>

  or use the profile.d sourcing method instead of shell hook.
• Environment activation doesn't persist in scripts — Use

  eval "$(conda shell.bash hook)"

  at the start of your script, or source the profile.d script.

• mamba activate

  fails — Try using

  conda shell.bash hook

  with

  mamba activate

  ; they're compatible.

• pixi shell-hook

  hangs — Use

  pixi run <command>

  instead for better reliability.