Skip to content
Tutorials Center
My learning

Topics

Lesson 49 of 149 ยท Modules and the Standard Library

Packages and pip

Learn how Python packages group modules into folders, how relative imports work, and how to install third-party code from PyPI with pip and requirements files.

A module is one file. A package is a folder of modules that belong together, imported with dotted names like email.message or shop.pricing. Packages are how big projects stay organized, and they're also the unit people share with the world.

Python's real superpower is that sharing. The Python Package Index (PyPI) hosts hundreds of thousands of packages, and the pip tool installs any of them with one command. In this lesson you'll build a small package, learn how imports inside it work, and see how pip, version pins and requirements files fit together.

Packages are folders of modules

A regular package is a folder that contains an __init__.py file. Each .py file inside is a submodule, and subfolders with their own __init__.py are subpackages:

TEXT
shop/
โ”œโ”€โ”€ __init__.py
โ”œโ”€โ”€ pricing.py
โ””โ”€โ”€ cart.py

With that layout you can write import shop.pricing, from shop import cart or from shop.pricing import add_tax. The browser runner has an in-memory file system, so you can build exactly this structure and import it:

Python Build a package

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The bookkeeping lines with importlib and sys.modules are only needed here because the files are created while Python is running; on your computer you'd create the folder in your editor and just import it.

Relative and absolute imports

Inside cart.py, the line from .pricing import add_tax is a relative import. The leading dot means "the package I'm in". Two dots (..) go up one level. The alternative is an absolute import that spells out the full path:

Python
# Inside shop/cart.py, both lines import the same function:
from .pricing import add_tax          # relative
from shop.pricing import add_tax      # absolute

Both styles are fine. Absolute imports are clearer for readers; relative imports keep working if you rename the top-level package. Pick one style per project.

Relative imports only work inside a package. Running python shop/cart.py directly fails with "attempted relative import with no known parent package", because a file run as a script isn't part of a package. Run it as a module instead, from the folder above shop: python -m shop.cart.

What __init__.py is for

__init__.py runs the first time any part of the package is imported. It can be empty, but it's also the place to define a package's public face. A common trick is to re-export the most useful names so users don't need to know your internal file layout:

Python Re-exporting from __init__.py

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

__all__ lists the names that from units import * would export. It also documents the public interface for readers and tools.

Folders without __init__.py can still be imported; they become namespace packages, a feature for splitting one package across several locations. For your own projects, include __init__.py; it's explicit and avoids surprises.

PyPI and pip

The standard library covers a lot, but sooner or later you'll want something it doesn't have: an HTTP client like requests, a web framework like Django or Flask, data tools like pandas. These live on PyPI (pypi.org), and you install them with pip, which comes with Python.

On your own computer, run pip from a terminal, not from inside Python:

Terminal
python -m pip install requests          # install the latest version
python -m pip install "requests==2.32.3"  # an exact version
python -m pip install --upgrade requests  # upgrade
python -m pip uninstall requests         # remove
python -m pip list                       # show installed packages
python -m pip show requests              # details about one package

Writing python -m pip instead of plain pip guarantees you're using the pip that belongs to the same Python you'll run your code with. On Windows the launcher form py -m pip does the same. Once a package is installed, you import it like any module: import requests.

Install packages into a virtual environment, not into your system-wide Python. Each project gets its own isolated set of packages, so two projects can need different versions without conflict. The lesson Virtual Environments and Project Setup walks through it.

Package names vs import names

The name you install and the name you import are usually the same, but not always. You install beautifulsoup4 and import bs4; you install Pillow and import PIL; you install python-dateutil and import dateutil. A package's PyPI page tells you both.

Checking what's installed

From inside Python, importlib.metadata reports installed distributions and their versions, and importlib.util.find_spec() tells you whether a module can be imported at all, without importing it:

Python Inspect installed packages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Results differ between environments, which is the point: your code can check for an optional package and fall back gracefully if it's missing.

Requirements files and version pins

When a project depends on packages, you need a way to tell other people (and your future self, and the server) exactly what to install. The classic approach is a requirements.txt file:

TEXT
# requirements.txt
requests>=2.31,<3
rich==14.0.0
python-dateutil~=2.9

Then one command installs everything:

Terminal
python -m pip install -r requirements.txt

The version specifiers mean:

Specifier Meaning
==14.0.0 Exactly this version
>=2.31,<3 At least 2.31, but below 3.0
~=2.9 "Compatible release": 2.9 or newer, below 3.0
no specifier Whatever is newest when you install

Applications usually pin exact versions so every install is identical. Libraries meant for others declare looser ranges so they play nicely with other packages. Modern projects often list dependencies in a pyproject.toml file instead; you'll meet it in the virtual environments lesson.

python -m pip freeze prints every installed package with its exact version in requirements format, a quick way to capture a working environment.

Installing packages in the browser

The editors on this site run Pyodide, a version of Python compiled for the browser. You can't run pip here, but two mechanisms do the same job:

  • Popular scientific packages such as numpy are bundled with Pyodide and load automatically when your code imports them (expect a download the first time).
  • micropip installs pure-Python packages from PyPI at runtime. It's asynchronous, so you await it.
Python micropip in the browser

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Top-level await works in this runner because it executes code asynchronously; in a normal script you'd simply use pip beforehand. micropip only handles pure-Python packages (or ones Pyodide has prebuilt), and it needs network access, so treat it as a convenience for experiments.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What turns an ordinary folder into a regular Python package?

    A folder with __init__.py is a regular package; the file runs when the package is first imported.
  2. 2. Inside shop/cart.py, what does from .pricing import add_tax import from?

    A single leading dot means "the current package", so this is shop.pricing.
  3. 3. Why is python -m pip install ... recommended over plain pip install ...?

    Computers often have several Pythons. python -m pip ties the install to the interpreter called python.
  4. 4. Which requirement allows version 2.9.4 but not 3.0?

    ~=2.9 is a compatible release: at least 2.9 and below 3.0.
  5. 5. You install beautifulsoup4. What do you write in your code?

    The install name and the import name can differ. This package installs as beautifulsoup4 and imports as bs4.

Summary

  • A package is a folder of modules with an __init__.py; import parts of it with dotted names.
  • Relative imports (from .pricing import ...) work only inside packages; run package modules with python -m package.module.
  • __init__.py runs once on first import and can re-export a clean public interface; __all__ lists it.
  • pip installs packages from PyPI; prefer python -m pip and install into a virtual environment.
  • requirements.txt with version specifiers (==, >=, ~=) makes installs repeatable; pip freeze captures an environment.
  • In the browser, Pyodide auto-loads bundled packages and micropip installs pure-Python ones.

Next: math and random, a tour of the standard library's number tools.