Install, virtual environments and pip

Here is the problem every Python developer hits in the first month. Project A needs version 1 of a package; project B needs version 2. If both install into the one Python on your machine, the second install overwrites the first and project A breaks. The fix is a virtual environment: a folder inside the project that holds its own copy of the Python interpreter and its own installed packages. Each project gets one, and they never touch each other.

Four tools do the whole job, and all of them come with Python:

• python (or python3): the interpreter that runs your files.
• venv: the standard-library module that creates a virtual environment, usually in a folder called .venv.
• pip: the package installer. It downloads packages from the Python Package Index (PyPI) into the active environment.
• requirements.txt: a text file listing your packages with exact versions, so anyone can rebuild the same environment.

Press Play for the macOS and Linux commands, then switch the Try it selector to Windows. The code tabs hold the commands for each system, and requirements.txt shows what pip freeze writes.

# 0. Check that Python is installed (3.10 or later for ADK)
python3 --version

# 1. Create a virtual environment named .venv inside the project folder
python3 -m venv .venv

# 2. Activate it (bash or zsh). Your prompt now starts with (.venv)
source .venv/bin/activate

# 3. Install packages into .venv, not into the system Python
python -m pip install google-adk
python -m pip list

# 4. Record the exact versions, so a teammate can rebuild the same environment
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt

# 5. Run your program with the venv's Python
python agent.py

# 6. Leave the environment when you are done
deactivate

The commands side by side

What to notice

1. Activate before you install. Activation puts the environment’s python and pip first in your shell’s search path and adds (.venv) to the prompt. Install before activating and the package lands in the system Python, which is the mistake the whole setup exists to prevent.
2. python -m pip is safer than pip. It runs the pip that belongs to whichever python is active, so you cannot install into the wrong place by accident.
3. .venv stays out of Git; requirements.txt goes in. The docs describe an environment as disposable: delete it and recreate it from the requirements file. Add .venv/ to .gitignore.
4. ModuleNotFoundError usually means the wrong environment. The package is installed somewhere, just not in the Python that is running. Check the prompt for (.venv) and activate again.
5. Pin versions when you share. pip freeze writes lines like google-adk==2.14.0. The == means “exactly this version”, so a teammate’s install matches yours.

Why this matters for AI work

pip install google-adk is the first ADK command you will run, and the adk command-line tool it installs lives inside .venv. When adk is “not found”, the environment is not active. The install lesson for ADK, Install and project layout, starts from exactly this point.