Python Environments With Miniforge

Python is a programming language. A Python environment keeps one project's Python program and add-on packages separate from other projects. Miniforge installs Conda, the program used here to create and manage that environment.

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.

New to text commands? Read how to open a terminal and run one command before using a command block. It explains the labels used below and what to copy.

Execution context: install and run Conda on your own computer. Use Windows PowerShell, macOS zsh, or Linux Bash from the exact project root named by the current step.

For Passport setup, follow Create A Reproducible Python Environment. Use this page for the specific failed check, or for a separate project that already has its own dependency definition. You do not need the Euler or GPU sections to complete local Python setup.

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.

Before Installing Anything#

Run:

conda --version
conda info --base

If both commands work, keep that installation and skip all installation sections below.

If you installed Conda while this command terminal was already open, including through Self Service or another managed installer, wait for installation to finish. Close only that command terminal, keep the terminal running the Passport open, and open a new standalone PowerShell window on Windows or Terminal window on macOS/Linux. Repeat both checks there before recovery or another installation. An already-open shell may not have loaded the setup changes. If the checks already worked, no restart or installation is needed.

If Self Service or IT reports Conda installed but the new terminal and the existing-installation recovery below cannot find it, ask IT how to open or initialize that installation. A search of common folders cannot rule out a managed installation elsewhere. Do not install a second copy.

On Windows, if PowerShell says that conda is unknown, search the Start menu for Miniforge Prompt, Miniconda Prompt, or Anaconda Prompt before downloading anything. If one exists, open it and run the two checks above. If they work, run this once in that prompt:

conda init powershell

Close only that setup terminal, keep the terminal running the Passport open, open a new PowerShell window, and repeat the checks. If more than one Conda prompt or installation appears, stop and choose one with setup help; do not uninstall or overwrite either copy.

On macOS or Linux, the Passport mission checks common personal installation folders and runs conda init for the selected shell when it finds exactly one existing installation. The change applies to a newly opened terminal, not the terminal that ran the command. Close that command terminal, open a new one, return to the practice folder, and repeat conda --version and conda info --base. If the check finds more than one installation, stop and choose one with setup help. Only install Miniforge after the check prints no-common-conda-installation and no managed installation is known.

conda --version
conda info --base

(
set -eu
tag="26.5.3-0"
temporary="$(mktemp -d "${TMPDIR:-/tmp}/ideal-passport-miniforge.XXXXXX")"
asset="Miniforge3-$tag-MacOSX-$(uname -m).sh"
installer="$temporary/$asset"
checksum="$installer.sha256"
cleanup() { rm -f -- "$installer" "$checksum"; rmdir -- "$temporary" 2>/dev/null || true; }
trap cleanup EXIT HUP INT TERM
printf 'Operating system: '; uname -s
printf 'Architecture: '; uname -m
case "$(uname -m)" in
  arm64|x86_64) ;;
  *) printf 'STOP: this Mac architecture has no approved installer in release %s.\n' "$tag" >&2; exit 1 ;;
esac
command -v curl >/dev/null || { printf 'STOP: curl is unavailable; use the official installer link.\n' >&2; exit 1; }
command -v shasum >/dev/null || { printf 'STOP: shasum is unavailable; do not run the installer.\n' >&2; exit 1; }
curl -fL --output "$installer" "https://github.com/conda-forge/miniforge/releases/download/$tag/$asset"
curl -fL --output "$checksum" "https://github.com/conda-forge/miniforge/releases/download/$tag/$asset.sha256"
(
  cd "$temporary"
  shasum -a 256 -c "$asset.sha256"
)
printf 'checksum-ok\n'
bash "$installer"
)

conda --version
conda info --base

(
set -eu
tag="26.5.3-0"
temporary="$(mktemp -d "${TMPDIR:-/tmp}/ideal-passport-miniforge.XXXXXX")"
asset="Miniforge3-$tag-$(uname -s)-$(uname -m).sh"
installer="$temporary/$asset"
checksum="$installer.sha256"
cleanup() { rm -f -- "$installer" "$checksum"; rmdir -- "$temporary" 2>/dev/null || true; }
trap cleanup EXIT HUP INT TERM
printf 'Operating system: '; uname -s
printf 'Architecture: '; uname -m
case "$(uname -m)" in
  aarch64|ppc64le|x86_64) ;;
  *) printf 'STOP: this Linux architecture has no approved installer in release %s.\n' "$tag" >&2; exit 1 ;;
esac
command -v curl >/dev/null || { printf 'STOP: curl is unavailable; use the official installer link.\n' >&2; exit 1; }
command -v sha256sum >/dev/null || { printf 'STOP: sha256sum is unavailable; do not run the installer.\n' >&2; exit 1; }
curl -fL --output "$installer" "https://github.com/conda-forge/miniforge/releases/download/$tag/$asset"
curl -fL --output "$checksum" "https://github.com/conda-forge/miniforge/releases/download/$tag/$asset.sha256"
(
  cd "$temporary"
  sha256sum -c "$asset.sha256"
)
printf 'checksum-ok\n'
bash "$installer"
)

conda --version
conda info --base

Return To The Passport Practice Folder#

Where: the new local command terminal, with the Python mission still open in your browser. A new terminal may start in your home folder rather than the project folder you used before.

1. In the mission, return to Prepare the Python practice folder.
2. Find the Practice folder ready box and copy its enter-folder command. If the box disappeared after a page reload, press Prepare practice folder again. The launcher reuses the existing folder and displays its path.
3. Paste that command into the new command terminal and press Enter. Keep its quotes: the folder name may contain spaces. Do not enter .transport.
4. At Return to the practice folder and read the definition, run the displayed read-only checks. The current folder and Git root must both match the Passport's displayed path. The branch must be practice/ followed by your GitHub username in lowercase. On Windows, backslashes and forward slashes can name the same folder.
5. Only continue when environment.yml is the unchanged training definition.

If Git reports no repository, the paths or branch differ, or the file is missing, stop and repeat the enter-folder command. Do not run git init, make a new clone, create a replacement file, or switch branches to clear the error. Use the help route if it still fails. Share the failed check and a sanitized error, not your private folder path.

Create A Project-Local Conda Environment#

Execution context: local terminal at the repository root after Conda initialization.

The Passport training project uses .venv as a project-local Conda prefix. Despite the folder name, it is a Conda environment, not one created with python -m venv.

The committed definition is the setup contract:

channels:
  - conda-forge
  - nodefaults
dependencies:
  - python=3.11

nodefaults excludes configured default channels when Conda resolves this file. A ToS plugin can still check configured channels before the file is read; use the channel-terms recovery below if that early check blocks creation. A real project may pin more dependencies, but should still document its channel policy and Python version.

Use the Create A Reproducible Python Environment mission for the exact Windows, macOS, or Linux commands. It enforces this order:

1. read the committed definition;
2. inspect .venv without changing it;
3. keep it only if it is a real directory, a Conda environment, and uses the declared Python version;
4. stop on a file, symbolic link, junction, incomplete environment, or version mismatch rather than deleting it;
5. prove .venv/ is ignored by Git;
6. create it from environment.yml only when absent;
7. activate it by its local prefix;
8. print sys.executable, the Python version, and the pip location;
9. select that same interpreter in the editor.

The Git-ignore check must succeed before the creation command:

git check-ignore -v --no-index .venv/conda-meta/history

Expected: Git prints the rule covering .venv/. If it prints nothing, stop and correct .gitignore before creating the environment.

The creation command is:

conda env create --prefix ./.venv --file environment.yml -y

Do not run it until the preceding inspection and Git-ignore checks pass. Do not remove or replace an existing .venv merely to make the command succeed.

After activation, verify the interpreter rather than trusting the prompt:

conda activate ./.venv
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version

All reported paths must belong to this repository's .venv. Install the real project only with the command documented by that project. Never improvise a second installer, install into Conda base, or use sudo pip to bypass an environment problem.

Recover From A Conda Channel-Terms Error#

Goal: create the Passport environment from its unchanged definition when CondaToSNonInteractiveError names repo.anaconda.com/pkgs/main or /pkgs/r. ToS means Terms of Service. The message alone does not prove that the exercise needs packages from those channels: the plugin can check configured channels before Conda reads the file's nodefaults entry.

Prerequisites: the practice repository is ready, environment.yml is unchanged, and the earlier environment-path and Git-ignore checks have passed. This recovery requires stable Conda 26.3 or newer. Older working Conda installations can still use the normal creation procedure above.

Execution context: your local practice-folder terminal: PowerShell on Windows, zsh on macOS, or Bash on Linux. Keep the Passport server terminal open.

1. If creation already succeeded, skip this recovery and verify the interpreter.
2. If .venv exists, return to Inspect the environment path. Reuse it only if the checks pass. Preserve a partial directory, file, or link; do not delete or overwrite it to retry.
3. Open the mission's Recover only from a Conda channel-terms error step and run its guarded command for your platform. It checks the folder, unchanged tracked definition, ignore rule, and Conda version before creation.
4. Continue at Activate the project environment and Verify the active interpreter. The interpreter and pip paths must be inside this .venv, and Python must report version 3.11.

The recovery still reads environment.yml. --override-channels with --channel conda-forge selects the channel for this one command, including the plugin's early check. --no-default-packages prevents personal default-package settings from adding undeclared packages. The ToS plugin stays enabled. No .condarc, shell profile, or global channel setting is changed.

Expected result: Conda selects only conda-forge, creates .venv from the definition, and does not request acceptance for the two reported channels. No Passport reset, second installation, or edited definition is needed.

Failure and help: if Conda is older than 26.3, the command stops before creation. Ask the lab IT administrator about an approved update of the existing installation, especially on a managed computer; do not update base or install another distribution as an unreviewed workaround. If a terms prompt or channel, network, or permission error remains, stop and ask for help. Do not accept terms just to unblock this exercise, disable the plugin, enable automatic acceptance, or change global channels. Any genuinely required channel access needs a separate decision by the authorized user or administrator.

For help, provide only the mission, OS, output of conda --version, the plugin version if known, and the error type. Do not send raw Conda configuration, private channel URLs, tokens, or full logs. See Incidents And Getting Help.

Technical basis checked on 2026-09-20: Conda 26.3 release notes document YAML input for conda create --file; the ToS plugin's pre-command hook checks configured channels before environment creation. These references do not establish anyone's licensing entitlement.

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#

The Python extension is separate from both VS Code and the Python interpreter. In the current local VS Code window, install or enable Python by Microsoft (ms-python.python) before using Python: Select Interpreter. The VS Code Python setup shows the exact search, expected result and recovery for a missing command or a managed-device block.

Open the Passport practice folder and select the executable printed by the mission's Verify the active interpreter step. A new integrated terminal must also use that same .venv; repeat the mission's activation and path checks there. Selecting an editor interpreter does not prove which Python an older terminal uses. The interpreter guide explains what to do if the environment is absent from the list.

For another editor, choose that same executable through its Python settings. Terminal-only learners can keep their verified command terminal without installing a VS Code extension. 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. Follow the Passport mission first, then use the Euler Python environment reference for project-specific work. It explains storage, module loading, batch-script activation, dependency installation, and recovery without duplicating a second setup recipe here.

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.

Python terminal/editor guidance checked on 2026-09-20 against Conda initialization, VS Code's Python setup and interpreter selection. This check does not refresh the unrelated Euler or GPU procedures above.

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