SyntaxPilot
Courses/Python/Lesson 30

Python · Lesson 30 of 40 · 10 min

Virtual environments, pip, project structure

queued

These are the notes for Python episode 30. Raju wants a UPI QR code on every bill. Drawing QR codes from scratch is weeks of work, but someone has already shared a package called qrcode. Importing it fails, installing it on his Ubuntu laptop is refused, and on another machine installing a package for one project silently breaks another. In this episode you learn pip and PyPI, invent virtual environments (one separate box of packages per project), write a requirements.txt so anyone can rebuild your setup, and lay out a project the way real Python projects are organised. Compiler examples run as-is in the SyntaxPilot compiler (Python 3.13); terminal commands were run for real (Python 3.13 venvs with pip 26, and Ubuntu 24.04's system pip for the PEP 668 error).

The problem: a package Python doesn't have

import qrcode

qr = qrcode.QRCode(border=1)
qr.add_data("upi://pay?pa=raju@upi&am=85")
qr.make()
print("QR size:", qr.modules_count)

Output:

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    import qrcode
ModuleNotFoundError: No module named 'qrcode'

Why: the standard library (episode 19) is what comes with Python. qrcode is a third-party package: code written by other people, published on PyPI (the Python Package Index, pypi.org), which holds hundreds of thousands of packages. It must be downloaded and installed first.

pip: the installer

PyPI is like an app store; pip is the Install button. pip commands are typed in a terminal (Command Prompt / PowerShell on Windows, Terminal on Mac and Linux), not inside a Python file.

Command What it does
pip install qrcode download and install the latest version
pip install requests==2.31.0 install an exact version (==)
pip install "requests>=2.31" at least this version
pip install -U qrcode upgrade to the newest version
pip uninstall qrcode remove it
pip list every installed package and its version
pip show qrcode details of one package
pip freeze installed packages in name==version form
python -m pip install ... the same, but guaranteed to use this python's pip

pip show qrcode (first lines):

Name: qrcode
Version: 8.0
Summary: QR Code image generator
Home-page: https://github.com/lincolnloop/python-qrcode

Attempt 1 on Ubuntu: refused

$ pip install qrcode
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    ...
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

Ubuntu's (and Debian's, Fedora's, Homebrew's) own tools are written in Python and depend on the system's packages, so the system refuses to let pip change them (the rule is called PEP 668). Notice the advice: create a virtual environment. Never use --break-system-packages on your own machine.

The next problem: two projects collide

On Windows or with a python.org install, pip install usually works, and the trouble arrives later. All projects share one folder of installed packages (called site-packages), and it can hold one version of each package.

Raju's old billing app was tested with requests 2.31.0. His new delivery app needs 2.32.3:

$ pip install requests==2.31.0     # for the billing app
...
Successfully installed certifi-2026.10.23 charset-normalizer-3.5.2 idna-3.20 requests-2.31.0 urllib3-2.8.0

$ pip install requests==2.32.3     # for the delivery app
    Found existing installation: requests 2.31.0
    Uninstalling requests-2.31.0:
      Successfully uninstalled requests-2.31.0
Successfully installed requests-2.32.3

The delivery app works; the billing app now runs a version it was never tested with. One shared cupboard for every project is the real problem.

Virtual environments

At home a big pot of dal is shared: add chilli and everyone's lunch is spicy. A tiffin box is packed for one person. A virtual environment (venv) is a tiffin box for one project: a folder containing its own link to the Python program and its own site-packages. Each project gets one, usually in a folder named .venv inside the project.

Real life Python
one big pot the global (system-wide) Python and its packages
a tiffin box each a virtual environment per project
picking up your own box activating the venv

Create, activate, use, deactivate

~/billing$ python3 -m venv .venv
~/billing$ source .venv/bin/activate          # Windows: .venv\Scripts\activate
(.venv) ~/billing$ which python               # Windows: where python
/home/raju/billing/.venv/bin/python
(.venv) ~/billing$ pip install requests==2.31.0
Successfully installed ... requests-2.31.0
(.venv) ~/billing$ deactivate
~/billing$
  • python3 -m venv .venv: -m runs a module as a program; the standard-library venv module creates the environment in the folder .venv. (On Windows the command is usually py -m venv .venv or python -m venv .venv.)
  • Activate it: source .venv/bin/activate on Linux/Mac, .venv\Scripts\activate on Windows (in PowerShell: .venv\Scripts\Activate.ps1). The prompt starts with (.venv).
  • While active, python and pip are the project's own; installs go into this box only.
  • deactivate closes it. Do the same in the delivery project with requests==2.32.3, and both apps keep their own version.
  • Editors such as VS Code detect .venv and use it automatically once you select it as the interpreter.

Which Python is running?

import sys

print("Python:", sys.version.split()[0])
print("Running from:", sys.prefix)
print("In a venv?", sys.prefix != sys.base_prefix)

Output in the SyntaxPilot compiler (global Python):

Python: 3.13.18
Running from: /usr/local
In a venv? False

sys.prefix is the folder of the running Python; sys.base_prefix is the original installation. Inside an active venv they differ, so the last line prints True and sys.prefix is the project's .venv folder.

requirements.txt: the shopping list

Raju sends the project to his cousin Neha, without the .venv folder (it's large and tied to his computer). She needs to know exactly which packages and versions to install. By convention that list goes in requirements.txt.

(.venv) ~/billing$ pip freeze > requirements.txt
(.venv) ~/billing$ cat requirements.txt
certifi==2026.10.23
charset-normalizer==3.5.2
idna==3.20
requests==2.31.0
urllib3==2.8.0

Raju installed only requests, but it needs four helper packages, its dependencies, so pip freeze lists them too, each pinned to an exact version. > sends the output into a file.

On Neha's laptop:

~/billing$ python3 -m venv .venv
~/billing$ source .venv/bin/activate
(.venv) ~/billing$ pip install -r requirements.txt

-r means "read the list of packages from this file". Same packages, same versions, one command.

Project structure

billing/
├── .venv/              ← never shared (listed in .gitignore)
├── billing/            ← the package: your code
│   ├── __init__.py
│   ├── bill.py
│   └── qr.py
├── tests/              ← tests (episode 29)
│   └── test_bill.py
├── main.py             ← starts the app
├── requirements.txt    ← exact packages to install
├── README.md           ← what it does and how to run it
└── .gitignore          ← files never to share: .venv/, __pycache__/
  • The code lives in a package folder (a folder of modules with __init__.py, episode 19).
  • Tests live in tests/ so pytest finds them.
  • README.md explains the project and how to set it up.
  • .gitignore lists files version control (git) should never share, starting with .venv/ and __pycache__/ (Python's cache of compiled files).
  • Bigger projects add pyproject.toml: the standard file for the project's name, version, dependencies and tool settings, used when you build or publish a package. A minimal one:
[project]
name = "billing"
version = "0.1.0"
dependencies = ["requests==2.31.0", "qrcode"]

if __name__ == "__main__":

When a file runs directly, Python sets its __name__ to "__main__". When another file imports it, __name__ is the module's name ("bill"). Code under this if runs only when the file is run directly, not when it's imported.

def final_bill(amount):
    if amount >= 100:
        return amount - amount // 10
    return amount

print("__name__ is", __name__)

if __name__ == "__main__":
    print("Bill:", final_bill(120))

Output:

__name__ is __main__
Bill: 108

If main.py did from bill import final_bill, the first print would show __name__ is bill and the Bill: line would be skipped.

Common mistakes

Mistake What you see Why Fix
import qrcode without installing ModuleNotFoundError: No module named 'qrcode' a third-party package activate the venv, pip install qrcode
pip install qrcode on Ubuntu, no venv error: externally-managed-environment the system Python is protected (PEP 668) python3 -m venv .venv first
installed in the venv but it isn't active ModuleNotFoundError: No module named 'qrcode' the global Python is running source .venv/bin/activate
pip install requests==2.32.3 globally Successfully uninstalled requests-2.31.0 one version for all projects one venv per project
copying or moving a .venv folder .venv/bin/pip: cannot execute: required file not found a venv stores absolute paths to its own folder delete it, recreate, pip install -r requirements.txt
pip installs into a different Python than python runs installed, but still ModuleNotFoundError two Pythons on the machine python -m pip install ...
naming your file qrcode.py AttributeError: module 'qrcode' has no attribute 'QRCode' (consider renaming '.../qrcode.py' if it has the same name as a library you intended to import) your file hides the package rename your file

Mini project: Raju's shop project from zero

$ mkdir shop && cd shop
$ python3 -m venv .venv && source .venv/bin/activate
(.venv) $ pip install qrcode pytest
Successfully installed iniconfig-2.3.1 packaging-26.3 pluggy-1.7.0 pygments-2.21.0 pytest-9.2.0 qrcode-8.0

Then write:

  • shop/__init__.py (empty), shop/bill.py with final_bill() (episode 29), shop/qr.py with a function that builds the payment QR code,
  • tests/test_bill.py with the pytest tests from episode 29 (from shop.bill import final_bill),
  • main.py that builds a bill and its QR code.
(.venv) $ pytest                                  # all green
(.venv) $ pip freeze > requirements.txt
(.venv) $ echo ".venv/" > .gitignore
(.venv) $ python main.py

The QR code from the start of the video now builds: for "upi://pay?pa=raju@upi&am=85", qr.modules_count is 29 (a 29 × 29 grid, QR version 3).

Practice

1. Make a venv, install qrcode, and print a QR code in the terminal with qr.print_ascii().

Solution
import qrcode
qr = qrcode.QRCode(border=1)
qr.add_data("chai")
qr.make()
qr.print_ascii()
print("Version:", qr.version)

Output (inside a venv with qrcode 8.0):

 ▄▄▄▄▄▄▄ ▄ ▄   ▄▄▄▄▄▄▄ 
 █ ▄▄▄ █ █ ▀▄█ █ ▄▄▄ █ 
 █ ███ █ ▄██ ▄ █ ███ █ 
 █▄▄▄▄▄█ ▄▀█▀█ █▄▄▄▄▄█ 
 ▄  ▄▄▄▄▄▄▀▄▀█▄  ▄ ▄▄▄ 
 ▀▀▄ ▀ ▄▀█▀▀ ▀▄█ █▄▄▄▄ 
 ▄▀▀▀ ▀▄▄▀▀▀▀  ▄  ▄▀██ 
 ▄▄▄▄▄▄▄ █▀▄▀█▄▄█▄▄█▀  
 █ ▄▄▄ █ █▄ ██▀▄█▀█▀▄█ 
 █ ███ █ ▀██▀▀ ▄ ▀▀▄▄▄ 
 █▄▄▄▄▄█ ▄▄█▄ ▀▀ ▀ █▀▀ 

Version: 1

A short text fits in the smallest QR code, version 1 (21 × 21).

2. Write requirements.txt, delete .venv, and rebuild it from the file.

Solution
(.venv) $ pip freeze > requirements.txt
(.venv) $ deactivate
$ rm -rf .venv                      # Windows: rmdir /s /q .venv
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ pip install -r requirements.txt

pip list now shows the same packages and versions as before.

3. Write a script that says whether it's running inside a virtual environment.

Solution
import sys

if sys.prefix != sys.base_prefix:
    print("Inside a venv:", sys.prefix)
else:
    print("Global Python:", sys.prefix)

Output in the SyntaxPilot compiler:

Global Python: /usr/local

Quick quiz

(.venv) ~/billing$ pip install -r requirements.txt
Successfully installed ... qrcode-8.0
(.venv) ~/billing$ deactivate
~/billing$ python3 main.py
ModuleNotFoundError: No module named 'qrcode'

Why? A. requirements.txt is wrong B. qrcode needs a restart C. the venv is not active D. pip freeze was not run

Answer

C. After deactivate, python3 is the global Python, which doesn't have qrcode. Run source .venv/bin/activate again (or run .venv/bin/python main.py).

Interview questions

  1. What is a virtual environment and why use one? An isolated folder with its own Python link and site-packages, so each project can have its own package versions without affecting others or the system.
  2. What does activating a venv actually do? It puts the venv's bin (Scripts on Windows) folder first on the PATH and changes the prompt, so python and pip refer to the venv's copies.
  3. pip freeze vs pip list? list is a readable table; freeze prints name==version lines suitable for requirements.txt.
  4. Why pin versions? So every machine (teammates, servers, CI) gets exactly the versions the code was tested with.
  5. Should .venv be committed to git? No. It's large, platform-specific and contains absolute paths. Commit requirements.txt (or pyproject.toml).
  6. What is if __name__ == "__main__": for? Code under it runs only when the file is executed directly, not when it's imported as a module.
  7. What is PEP 668? The rule that lets operating systems mark their Python as "externally managed", so pip refuses to install into it and you use a venv instead.

Glossary

Term Meaning
package (third-party) reusable code written by others, installed separately from Python
standard library the modules that come with Python (re, json, unittest, venv, ...)
PyPI the Python Package Index, pypi.org: where packages are published
pip Python's package installer
terminal a text window where you type commands (Terminal, Command Prompt, PowerShell)
version a numbered release of a package, e.g. 2.31.0
pinning fixing an exact version with ==
dependency a package another package needs in order to work
site-packages the folder where installed packages are stored
global Python the Python installed for the whole computer
virtual environment (venv) a project's own isolated Python setup and packages
.venv the usual folder name for a project's virtual environment
activate / deactivate start / stop using a venv in the current terminal
PATH the list of folders the terminal searches for commands
sys.prefix / sys.base_prefix the running Python's folder / the original installation's folder
requirements.txt a list of packages and versions to install with pip install -r
pip freeze prints installed packages as name==version
externally managed environment an OS-protected Python where pip may not install (PEP 668)
project structure how a project's folders and files are laid out
README.md a file describing the project and how to use it
.gitignore a list of files git should not track or share
pyproject.toml the standard project file: name, version, dependencies, tool settings
__name__ a variable holding the module's name, or "__main__" when the file runs directly
__pycache__ a folder where Python caches compiled versions of your modules

Summary

  • Third-party packages live on PyPI; pip installs them from a terminal.
  • One global set of packages means one version for every project, and modern Linux refuses global installs.
  • Each project gets its own virtual environment: python3 -m venv .venv, activate it, then pip install.
  • sys.prefix != sys.base_prefix tells you you're in a venv.
  • pip freeze > requirements.txt and pip install -r requirements.txt rebuild the same setup anywhere; share the list, never the .venv.
  • Lay projects out with a package folder, tests/, requirements.txt, README.md, .gitignore, and guard script code with if __name__ == "__main__":.
  • Next episode: downloading fifty bills one after another takes forever. You'll invent threads and multiprocessing.