Python Environments With Miniforge

Goal: create isolated, reproducible Python environments locally and use the project's declared setup instead of accumulating packages in one global Python.

Prerequisites: know whether the project already declares Python and package versions in pyproject.toml, environment.yml, or another setup file.

The canonical practical exercise is Reproducible Python Environment.

Mental Model#

• Miniforge installs the conda/mamba environment managers with conda-forge.
• An environment isolates a Python interpreter and packages for one project.
• conda is useful for Python and binary/system dependencies.
• python -m pip installs Python packages into the currently selected Python.
• The repository, not an agent's chat history, declares how to recreate the environment.

Do not install project packages into Conda base, the operating-system Python, or with sudo pip.

Install Miniforge On Windows#

Execution context: Windows laptop - browser and Miniforge Prompt.

1. Download the Windows x86-64 installer from the official Miniforge repository.
2. Choose Just Me and an installation path without unusual characters.
3. Keep Start Menu shortcuts. Do not force-add Miniforge to the global Windows PATH when the installer warns about conflicts.
4. Open Miniforge Prompt.

Verify:

conda --version
conda info --base

Expected result: conda reports a version and the base path points to your personal Miniforge installation.

To use Conda from PowerShell, run conda init powershell once from Miniforge Prompt, close every PowerShell window, and open a new one.

Install Miniforge On macOS Or Linux#

Execution context: local macOS zsh or Linux Bash.

Download the installer matching the current operating system and CPU from the official Miniforge releases. Then run the downloaded filename, for example:

bash Miniforge3-MacOSX-arm64.sh

Use Miniforge3-MacOSX-x86_64.sh, Miniforge3-Linux-x86_64.sh, or another official filename when that matches the machine. Do not guess architecture; check with:

uname -s
uname -m

Accept shell initialization when prompted, close the terminal, open a new one, then verify:

conda --version
conda info --base

Optional: prevent automatic activation of base:

conda config --set auto_activate_base false

Create A Project Environment#

Execution context: local terminal after Conda initialization.

Use the Python version declared by the project. For a training project that explicitly chooses Python 3.11:

conda create -n passport-python python=3.11 -y
conda activate passport-python
python --version
python -m pip --version

Expected result: both Python and pip paths belong to passport-python. Use where python on Windows or which python on macOS/Linux to inspect the path.

Install the project exactly as its README declares. Common patterns include:

python -m pip install -e '.[dev]'

or:

conda env create -f environment.yml

Do not run both unless the project explicitly combines them.

Record Reproducibility#

Prefer a project contract containing:

An environment export can contain platform-specific transitive packages. Review it before committing and prefer a concise hand-maintained environment file when possible.

VS Code#

1. Open the project folder.
2. Run Python: Select Interpreter from the Command Palette.
3. Select the project environment.
4. In the integrated terminal, run:

python --version
python -m pip --version

For notebooks, select the same environment in the kernel picker.

Euler Python Environment#

Do not copy a local environment directory to Euler. Create an Euler-native virtual environment using an available software stack.

The following module path was verified on 2026-08-04. Recheck with module spider python/3.11.6 if it fails.

Execution context: Euler login node - Bash for inspection and lightweight environment creation. Use a CPU allocation when installation compiles or does substantial work.

module purge
module load stack/2024-06 gcc/12.2.0 python/3.11.6
python --version
read -r -p "Short project name: " project_name
case "$project_name" in
  ''|*[!A-Za-z0-9._-]*)
    printf 'STOP: use only letters, numbers, dot, underscore, or hyphen.\n' >&2
    project_name=''
    ;;
esac
venv_path="$HOME/venvs/$project_name"
if [ -n "$project_name" ] && [ -e "$venv_path" ]; then
  printf 'STOP: %s already exists; nothing was overwritten.\n' "$venv_path" >&2
elif [ -n "$project_name" ]; then
  mkdir -p "$HOME/venvs"
  python -m venv "$venv_path"
  source "$venv_path/bin/activate"
  python -m pip install --upgrade pip
fi

Then follow the project's dependency instructions. Keep environments in $HOME, not shared /cluster/work/fuge.

For GPU Python, use the python_cuda/3.11.6 module only when the project needs that toolchain and after checking current availability:

module spider python_cuda/3.11.6

PyTorch And CUDA#

PyTorch wheel and CUDA combinations change. Do not preserve a copied wheel URL as permanent lab policy.

1. Create/activate a clean project environment.
2. Open the official PyTorch installation selector.
3. Select the actual operating system, package manager, language, and CPU/CUDA platform.
4. Run the generated command in the intended environment.
5. Record the selected versions in project configuration or documentation.

On Euler, perform the install/setup in a CPU allocation when it is substantial; request a GPU only for the actual GPU verification.

Verification inside an allocated GPU job:

python - <<'PY'
import torch

print("torch:", torch.__version__)
print("runtime CUDA:", torch.version.cuda)
print("CUDA available:", torch.cuda.is_available())
if torch.cuda.is_available():
    print("GPU:", torch.cuda.get_device_name(0))
PY

Detecting a GPU is a smoke test, not evidence that training uses it efficiently. Follow the Euler GPU Track.

AI-Agent Reproducibility#

Safe inspection prompt:

Goal: explain how this Python project is recreated and verified.
Context: inspect README, pyproject.toml, environment files, and tests.
Constraints: do not install packages or edit files; do not read .env or secrets.
Verification: identify exact commands supported by repository evidence.
Output: missing reproducibility information and the smallest patch plan.

Ask why each new dependency is needed. Do not let an agent update many packages "just in case" or claim compatibility without running the project checks.

Common Failures And Safe Recovery#

• conda not found: open Miniforge Prompt or initialize the current shell, then restart it.
• Wrong interpreter: reactivate the environment and reselect it in VS Code.
• pip installs elsewhere: compare python -m pip --version with the selected Python path.
• Environment works only on one machine: recreate from declarations and document missing platform/system requirements.
• CUDA unavailable: compare driver, selected PyTorch build, allocation, and device placement; do not install random CUDA versions into the same env.

Verification#

• Environment creation and installation follow project-owned files.
• Tests or the documented smoke check run in a newly created environment.
• git status --short does not show an environment, cache, or generated data.
• GPU package instructions came from the current official selector.

Ask For Help When#

Dependency declarations conflict, private packages lack documented access, binary/CUDA compatibility is unclear, or installation requires global changes.

Verified: 2026-08-04. Review by: 2026-11-04. Owner: lab software maintainer.