Python Environment, Installation, CLI, Editors, and First Suite: Diagnostics, Failure Modes, and Production Practices

1. The diagnostic sequence

flowchart TD
F[Preserve first failure] --> V[Robot / Python / tool versions]
V --> P[Executable and PATH resolution]
P --> D[Dependency installation location]
D --> C[Working directory and selected source]
C --> I[Parse/import/keyword layer]
I --> O[Output directory permissions / encoding]
O --> E[Editor / CI / container environment]
E --> X[Least destructive correction]
X --> R[Rerun smallest controlled slice]

The sequence begins above the suite logic because Chapter 02 incidents often prevent Robot from reaching the suite at all. If python -m robot --version fails, there is no value debugging a keyword. If the wrong test path was selected, changing assertions only introduces a second defect.

2. Failure: robot command not found

This message usually means the shell cannot find a robot console launcher on PATH. It does not prove Robot Framework is uninstalled everywhere.

PowerShell

Get-Command robot -ErrorAction SilentlyContinue
.\.venv\Scripts\python.exe -m robot --version

POSIX

command -v robot || true
./.venv/bin/python -m robot --version

If the explicit environment Python reports the expected version, the project environment is healthy; only launcher resolution differs. Activate the environment for convenience or keep using the explicit/module form. Do not globally reinstall Robot Framework merely to make a short command appear.

3. Failure: pip installed into a different Python

The classic symptom is: pip install robotframework reports success, but the intended python -m robot says the module is missing. Compare ownership directly.

python -c "import sys; print(sys.executable)"
pip --version
python -m pip --version
python -m pip show robotframework

The output from pip includes its installation location and associated Python. If bare pip and python -m pip refer to different environments, the fix is not a PYTHONPATH hack. Install through the intended interpreter.

4. Intentionally broken example: a fresh environment with no Robot package

Create a second disposable environment named .venv-broken. This is safer than corrupting the working .venv or uninstalling packages from a shared interpreter.

Windows PowerShell

py -3.12 -m venv .venv-broken
New-Item -ItemType Directory -Force evidence | Out-Null
.\.venv-broken\Scripts\python.exe -m robot --version *> evidence\missing-robot.txt
$LASTEXITCODE
Get-Content evidence\missing-robot.txt
.\.venv\Scripts\python.exe -m robot --version

macOS/Linux shell

python3.12 -m venv .venv-broken
mkdir -p evidence
./.venv-broken/bin/python -m robot --version > evidence/missing-robot.txt 2>&1 || true
cat evidence/missing-robot.txt
./.venv/bin/python -m robot --version

The broken environment should report that the robot module is unavailable. The healthy environment should report 7.4.2. You have preserved the failure as evidence and isolated the cause to dependency state inside one interpreter context. No suite source was changed.

5. Failure: stale or moved virtual environment

Virtual environments contain interpreter paths and launchers tied to how they were created. Copying a .venv between machines, moving it between incompatible paths, or upgrading/removing the base interpreter can produce confusing failures. Treat the environment as disposable runtime state.

Safer recovery:

1. Preserve dependency declarations and any diagnostic output.
2. Record the failing environment's interpreter/version if it still starts.
3. Create a fresh environment from the intended supported Python.
4. Reinstall from the reviewed requirements/lock data.
5. Rerun the smallest suite with a new output directory.

Do not hand-edit activation scripts or environment metadata as the default repair strategy.

6. Failure: unsupported or mismatched Python/tool version

Robot Framework 7.4.2 requires Python 3.8+. If the interpreter is older, installation should not be forced with unsupported flags. Upgrade or select a supported interpreter. Conversely, a Python 3.8/3.9 environment may run Robot Framework correctly but fail current RobotCode requirements because RobotCode currently requires Python 3.10+.

7. Failure: results appear in an unexpected directory

A relative output path is interpreted by the process in the context of its working directory. IDEs, task runners, and CI can start a process from a different directory than an interactive shell. Always inspect the current directory when paths surprise you.

python -c "from pathlib import Path; print(Path.cwd())"
python -m robot --outputdir results/diagnostic tests/environment.robot

For repository automation, establish a documented repository-root execution convention or compute an absolute artifact path in the wrapper. Do not scatter cd commands through tests to compensate for an unclear project boundary.

8. Failure: output permissions or filesystem restrictions

Robot can execute tests yet fail to write result files if the target directory is not writable, the filesystem is read-only, disk space is exhausted, or a CI/container user lacks ownership. Diagnose the filesystem separately from test semantics.

Use a harmless write preflight inside the intended disposable result root. For example, create and remove a synthetic text file manually or with a short Python command. Never respond by running the entire suite as administrator/root unless the target environment explicitly requires and governs that privilege.

from pathlib import Path
root = Path("results/preflight")
root.mkdir(parents=True, exist_ok=True)
probe = root / "write-check.txt"
probe.write_text("ok\n", encoding="utf-8")
print(probe.resolve(), probe.read_text(encoding="utf-8").strip())
probe.unlink()

9. Failure: encoding and path-name surprises

Robot Framework source is designed for Unicode text, but the full toolchain includes the terminal, editor, filesystem, Python, external libraries, and CI log collector. A source file saved with unexpected encoding or a path containing characters mishandled by an external tool can create failures that appear unrelated to the suite.

For the baseline lab, save .robot and text configuration as UTF-8, keep the project path simple, and inspect the exact file the runner opened. Do not “fix” encoding issues by replacing meaningful text with question marks or changing global system locale settings without understanding the affected boundary.

10. Failure: green locally, broken in CI

A local PASS does not prove portability. Common hidden dependencies include a globally installed Robot version, an activated shell, a workstation-only environment variable, an editor-defined working directory, or a result directory that already exists with permissive ownership. Preserve output.xml, log.html, and report.html from the failing CI slice before changing the environment.

11. Troubleshooting anti-patterns

• Arbitrary PYTHONPATH edits: can hide wrong project packaging/import ownership.
• Global reinstall: can make one shell green while changing unrelated projects.
• Deleting results/ first: destroys evidence before root cause is known.
• Blind retries: do not repair deterministic interpreter or import mismatches.
• Running as administrator/root: can mask ownership defects and widen risk.
• Editor-only fixes: may leave CLI and CI broken.

12. Knowledge check

13. Summary and next step

Environment diagnosis is evidence-driven: interpreter → launcher → installed package → working directory → selected source → writable result path → editor/CI boundary. Lesson 5 turns that sequence into a complete checkpoint from an empty directory, including two clean-shell runs and one reversible mismatch.

Further reading and current primary references

Version-sensitive statements in this lesson were checked on 2026-08-30. The mandatory path pins Robot Framework 7.4.2, the current stable release at the time of authoring. Robot Framework 7.5b1 is a pre-release and is not required. Robot Framework itself requires Python 3.8+; the current RobotCode toolchain has a stricter Python 3.10+ runtime requirement, so editor compatibility must be checked separately from framework compatibility.

• Robot Framework on PyPI — installation, Python requirement, release history
• Robot Framework 7.4.2 User Guide
• Robot Framework 7.4.2 release notes
• Python documentation — venv
• pip User Guide
• uv documentation — virtual environments
• RobotCode — current getting-started and environment guidance
• RobotCode project — current runtime requirements and configuration model
• External Testdoc — replacement for the deprecated built-in Testdoc