Chapter 6: Creating and managing Python virtual environments

Introduction

Introduces Python packages as reusable code and explains why virtual environments are a foundational practice before installing packages for the chatbot project.

• Packages and virtual environment purpose: Explain that prewritten Python packages can save programming effort and that understanding virtual environments before installing packages for the chatbot project supports clean, professional development.
  Why it matters: It explains why the chapter addresses virtual environments before adding packages to the chatbot project.

Key terms: Python packages, virtual environments

6.1 Why virtual environments matter

This section explains why each Python project should have its own virtual environment before packages are installed.

• Python packages and versions: Describe what a Python package is and why two projects might need different versions of the same package.
  Why it matters: Package versions are the source of the conflicts that virtual environments help prevent.
• Per-project package isolation: Explain how separate virtual environments prevent package-version conflicts, and state when to create one for a project.
  Why it matters: Isolation lets you install what one project needs without disrupting another.
• Reproducibility and easy cleanup: Explain how virtual environments help others re-create a project's package setup and make it easier to remove those packages when the project is finished.
  Why it matters: An environment is easier to share, reproduce, and clean up when its packages belong to one project.

Key terms: package, library, version, virtual environment, isolation, version conflict, reproducibility, cleanliness, virtual environment folder

6.2 Creating a virtual environment

6.2.1 Navigate to your project folder

6.2.2 Create the virtual environment

This subsection shows how to create a project-specific virtual environment, recognize its silent completion, and recover if creation fails.

• Virtual environment creation and verification: Describe how to run `python3.13 -m venv .venv` in the project folder, wait for the prompt to return, and verify that a `.venv` folder appears when you list the directory.
  Why it matters: Checking for `.venv` confirms that the project’s Python environment is ready before you try to use it.
• Failed creation recovery: Explain what to try if environment creation appears to hang in VS Code’s integrated terminal or activation later reports that the file or directory does not exist.
  Why it matters: These checks help distinguish a slow command from an environment that was never created.

Key terms: python3.13 -m venv .venv, .venv, virtual environment, VS Code’s integrated terminal, macOS Terminal, no such file or directory

6.2.3 Understanding the venv command

This section explains how to read the virtual environment creation command and why the book names its environment folder .venv.

• Virtual environment command parts: Explain that python3.13 -m venv .venv runs Python’s built-in venv module to create a virtual environment in a folder named .venv.
  Why it matters: Reading the command correctly helps you distinguish the tool Python runs from the folder it creates.
• Environment folder naming convention: Justify using .venv as the environment folder name in this book instead of .env.
  Why it matters: A recognizable folder name avoids confusion with a project’s secrets and configuration file.

Key terms: python3.13 -m venv .venv, venv module, .venv folder, .venv, .env

6.2.4 What is inside the venv folder?

This section explains the main contents of a virtual environment folder and why it resembles a separate Python installation inside a project.

• Virtual environment folder contents: Describe how the venv folder acts as a miniature Python installation inside a project, and identify the roles of bin/, lib/, and pyvenv.cfg.
  Why it matters: This layout helps you see where a project's Python tools and packages live without confusing them with the system Python.

Key terms: venv folder, bin/, lib/, pyvenv.cfg, system Python

6.3 Activating and deactivating a virtual environment

This section explains why creating a virtual environment is not enough: the terminal must be told to use it.

• Virtual environment activation: Explain that a virtual environment is a folder on disk that the terminal does not use automatically. Activating it tells the terminal to use that folder’s Python version and packages instead of the system-wide ones.
  Why it matters: Creating an environment alone does not make your terminal use its Python and packages.

Key terms: virtual environment, activate, global installation of Python, system-wide

6.3.1 Activating the virtual environment

This section explains how activation makes terminal Python commands use the virtual environment and how the prompt shows that it is active.

• Virtual environment activation effects: Explain that activation changes the terminal’s environment variables so python3 and pip use the copies in .venv rather than system-wide installations, and that the (.venv) prompt prefix indicates the environment is active.
  Why it matters: This lets you tell whether your terminal is using the project’s isolated Python environment.

Key terms: activation, environment variables, python3, pip, .venv, (.venv) prefix

6.3.2 Verifying activation

This subsection shows how to confirm that activation makes Python point to the project’s virtual environment rather than a system-wide installation.

• Python Path After Activation: Explain how Python’s location confirms virtual-environment activation: its path should be inside the project’s .venv folder rather than at a system-wide Python location.
  Why it matters: Checking the path tells you whether you are using the project’s virtual environment.

Key terms: Python path, .venv folder, system-wide installation of Python

6.3.3 Deactivating the virtual environment

This section explains how to leave and return to a virtual environment and how to avoid using the wrong Python environment for a project.

• Leaving and returning to venv: Describe what happens when you deactivate the virtual environment and how to resume working in it.
  Why it matters: The prompt helps you tell which Python environment you are using.
• Pip installation destination: Explain why you should check the (.venv) prefix before installing packages with pip.
  Why it matters: Checking before installation keeps project packages in the intended environment.
• Existing environment in VS Code: State what to choose if VS Code offers to create a virtual environment for this project.
  Why it matters: Selecting the existing environment keeps VS Code pointed at the project environment already created.

Key terms: virtual environment, system installation of Python, (.venv) prefix, pip install, global Python installation, VS Code, .venv environment

6.4 Installing packages with pip

This section introduces pip as the standard Python package installer and notes that packages can be installed into an active virtual environment.

• Pip and virtual environments: Explain that pip is the standard Python package installer and that, with a virtual environment active, packages can be installed into it.
  Why it matters: This connects activating the environment with adding the packages your project needs.

Key terms: pip, virtual environment, packages

6.4.1 What is pip?

This section explains where pip gets Python packages and why pip and pip3 are interchangeable inside an activated virtual environment.

• Pip and PyPI roles: Explain that pip installs Python packages by connecting to the Python Package Index (PyPI), an online repository of Python libraries.
  Why it matters: This distinction helps you understand what the installation tool does and where packages come from.
• Pip versus pip3: Distinguish pip from pip3 on systems with multiple Python versions, and explain why either name works inside an activated virtual environment.
  Why it matters: It explains why the book can consistently use pip within an activated virtual environment.

Key terms: pip, Python Package Index, PyPI, Python packages, pip3, activated virtual environment, Python 3

6.4.2 Installing the Ollama Python package

This subsection explains why the Ollama Python library is needed to build a chatbot that uses a local Ollama server.

• Ollama Python library role: Explain how the Ollama Python library lets a script communicate with the Ollama server on your machine, sending messages to a model and processing its responses instead of relying on terminal prompts.
  Why it matters: This is the connection that lets your Python code use the local model in a chatbot.

Key terms: Ollama Python library, Ollama server, scripts

6.4.3 Installing Streamlit

This section identifies Streamlit as the chatbot’s web-interface framework and explains why its many dependencies are normal and contained in the virtual environment.

• Streamlit role and dependencies: Explain that Streamlit will provide the chatbot’s web interface and that the additional packages it needs are normal and remain inside the virtual environment’s venv folder.
  Why it matters: You can recognize why installing Streamlit adds other packages without worrying that their presence means something went wrong.

Key terms: Streamlit, web interface, dependencies, virtual environment, venv folder

6.4.4 Checking the installed packages

This section shows that checking a virtual environment’s installed packages reveals both packages you installed directly and the dependencies they brought with them.

• Installed packages and dependencies: Explain why the list of packages in the virtual environment contains more than the two packages directly installed.
  Why it matters: A longer-than-expected package list is normal when installed packages have dependencies.

Key terms: virtual environment, dependencies, ollama, streamlit

6.5 Freezing and restoring dependencies

This section introduces requirements.txt as a way to record the packages and versions in a virtual environment so the setup can be shared or re-created.

• Purpose of requirements.txt: Explain that requirements.txt records each installed package and its version number so a virtual environment’s setup can be shared with a teammate or re-created on another machine.
  Why it matters: Recording package versions gives someone else the information needed to re-create the same setup.

Key terms: requirements.txt, virtual environment, package, version number

6.5.1 Creating the requirements.txt file

Explains how a requirements.txt file records the exact package versions in a Python environment so the environment can be re-created elsewhere.

• Frozen package requirements: Explain that freezing requirements records a snapshot of the environment in a file, with each package pinned to an exact version so the environment can be re-created on another machine.
  Why it matters: Recording exact versions gives you a way to reproduce the project's environment elsewhere.

Key terms: freezing, requirements.txt, ==

6.5.2 Restoring an environment from requirements.txt

This subsection explains how pip restores the packages and versions listed in requirements.txt.

• Restoring listed package versions: Explain that pip’s -r flag reads requirements.txt and installs every listed package at its specified version, allowing someone else or future you to set up the same environment.
  Why it matters: A requirements file lets you recreate the same package setup later or on another machine.

Key terms: pip, -r flag, requirements.txt

6.5.3 Keeping requirements.txt updated

Explains how to keep a project's dependency list current and what to share instead of the virtual environment folder.

• Updated dependency list: Explain that after installing a new package, you should freeze the requirements again so requirements.txt stays current.
  Why it matters: An updated requirements.txt reflects packages added to the project.
• Sharing requirements instead of .venv: Explain why you should share requirements.txt rather than the .venv folder, and describe how .gitignore helps when using Git.
  Why it matters: Sharing the small requirements file avoids distributing a bulky, machine-specific folder that can be recreated.

Key terms: freeze, requirements.txt, .venv, .gitignore, Git

6.5.4 The complete virtual environment workflow

6.6 Exercises

6.7 Summary