Python pip & venv Basics - Ryan's College Notes

💡Note: If you're serious about Python development (and want an easier time working with multiple projects), look into pyenv instead of venv. Check out their GitHub & docs for more information.

pip Basics

pip is the standard package manager for Python. it allows you to install and manage packages from the Python Package Index (PyPI) and other repositories.

Ensure pip is Available

first, check if pip is installed and available:

# check pip version
python3 -m pip --version
or on windows
py -m pip --version

to ensure smooth package installation, upgrade pip and install essential tools:

# upgrade pip, setuptools, and wheel
python3 -m pip install --upgrade pip setuptools wheel
windows version
py -m pip install --upgrade pip setuptools wheel

setuptools and wheel help ensure you can install packages from source archives when pre-built wheels aren't available.

Virtual Environments

virtual environments allow you to create isolated Python environments for different projects, preventing package conflicts and keeping dependencies organized.

Creating Virtual Environments

you can create a virtual environment to isolate packages for a specific project:

# create and activate virtual environment (unix/mac)
python3 -m venv tutorial_env
source tutorial_env/bin/activate
windows version
py -m venv tutorial_env
tutorial_env\Scripts\activate

Virtual Environment Tools

there are two main tools for creating Python virtual environments:

venv (Built-in)

available by default in Python 3.3+ and installs pip in Python 3.4+:

# unix/mac
python3 -m venv {DIR}
source {DIR}/bin/activate
windows
py -m venv {DIR}
{DIR}\Scripts\activate

virtualenv (Third-party)

needs to be installed separately but automatically includes pip, setuptools, and wheel:

# unix/mac
python3 -m virtualenv {DIR}
source {DIR}/bin/activate
windows
virtualenv {DIR}
{DIR}\Scripts\activate

Virtual Environment Workflow

common workflow for managing virtual environments:

# install virtualenv if not using venv
pip install virtualenv
create new virtual environment for a project
mkvirtualenv HelloWorld
bind environment with current working directory
setprojectdir .
deactivate current environment
deactivate
activate environment to work on it
workon HelloWorld

Installing Packages

pip installs packages from the Python Package Index using requirement specifiers - a project name followed by optional version constraints.

Basic Installation

install the latest version of a package:

python3 -m pip install "SomeProject"

Version Constraints

install specific versions or version ranges:

# install specific version
python3 -m pip install "SomeProject==1.4"
install version range
python3 -m pip install "SomeProject>=1,<2"
install compatible version
python3 -m pip install "SomeProject~=1.4.2"

Upgrading Packages

upgrade an already installed package to the latest version:

python3 -m pip install --upgrade SomeProject

User Installation

install packages for the current user only (has no effect inside virtual environments):

python3 -m pip install --user SomeProject

Advanced Installation

Source Distribution vs Wheels

pip can install from two formats:

Source Distributions (sdist): source code that needs to be built locally
Wheels: pre-built distributions that install faster

pip prefers wheels when available and will build and cache wheels from source distributions for future use.

Requirement Files

install multiple packages from a requirements file:

python3 -m pip install -r requirements.txt

Installing from Version Control

install directly from version control repositories in editable mode:

# from git
python3 -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git
from mercurial
python3 -m pip install -e SomeProject @ hg+https://hg.repo/some_pkg
from svn
python3 -m pip install -e SomeProject @ svn+svn://svn.repo/some_pkg/trunk/
from specific branch
python3 -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git@feature

Installing from Alternate Indexes

install from package repositories other than PyPI:

python3 -m pip install --index-url http://my.package.repo/simple/ SomeProject

Installing from Local Archives

install from local files or directories:

# from local archive
python3 -m pip install ./downloads/SomeProject-1.0.4.tar.gz
from local directory without checking PyPI
python3 -m pip install --no-index --find-links=file:///local/dir/ SomeProject
python3 -m pip install --no-index --find-links=/local/dir/ SomeProject
python3 -m pip install --no-index --find-links=relative/dir/ SomeProject

Installing Package Extras

some packages provide optional features through "extras":

# install with extras
python3 -m pip install 'SomePackage[PDF]'
python3 -m pip install 'SomePackage[PDF]==3.0'
install editable project with extras
python3 -m pip install -e '.[PDF]'

Package Management

Listing Installed Packages

# list all installed packages
python3 -m pip list
list outdated packages
python3 -m pip list --outdated
show package information
python3 -m pip show SomeProject

Generating Requirements Files

# generate requirements.txt with current packages
python3 -m pip freeze > requirements.txt
install from requirements file
python3 -m pip install -r requirements.txt

Uninstalling Packages

# uninstall a package
python3 -m pip uninstall SomeProject
uninstall multiple packages
python3 -m pip uninstall -r requirements.txt