Virtual Environments and pip

python3 -m venv .venv                 # create, uses the python that ran it
python3 -m venv --upgrade-deps .venv  # also upgrade the bundled pip
python3 -m venv --system-site-packages .venv   # also see system packages
python3 -m venv --clear .venv         # wipe and recreate in place
python3 -m venv --prompt myapp .venv  # custom name in the shell prompt

.venv/bin/python -m pip install requests   # no activation needed, always works

# From version control, a local path, or a URL
python -m pip install "git+https://github.com/psf/requests.git@v2.32.3"
python -m pip install "git+https://github.com/org/repo.git@main#egg=pkg"
python -m pip install "pkg @ git+https://github.com/org/repo.git"
python -m pip install ./local/wheel-1.0-py3-none-any.whl
python -m pip install -e "./libs/mylib[dev]"

python -m pip list                    # everything installed
python -m pip list --outdated         # what has a newer release
python -m pip list --not-required     # top-level only, not pulled in as a dep
python -m pip show requests           # version, location, Requires, Required-by
python -m pip show -f requests        # plus every installed file
python -m pip check                   # report broken or conflicting deps
python -m pip uninstall requests      # -y to skip the prompt
python -m pip cache dir; python -m pip cache info
python -m pip cache purge             # delete the whole wheel cache
python -m pip download -d ./wheels -r requirements.txt   # fetch, do not install
python -m pip install --no-index --find-links ./wheels -r requirements.txt
python -m pip config list             # where settings come from
python -m pip --version               # also prints the python it belongs to

python -m pip freeze > requirements.txt

# requirements.txt, the full grammar
requests==2.32.3
django>=5.0,<6.0
uvicorn[standard]==0.30.6
numpy==2.1.1 ; python_version >= "3.10"      # environment marker
pywin32==306 ; sys_platform == "win32"
-r requirements-base.txt                     # include another file
-e .                                         # the project itself
--index-url https://pypi.org/simple          # options are allowed inline
torch==2.4.1 --hash=sha256:abc...            # requires --require-hashes

python -m pip install pip-tools
pip-compile requirements.in -o requirements.txt        # resolve and pin
pip-compile --upgrade-package django requirements.in   # bump just one
pip-compile --generate-hashes requirements.in          # verifiable
pip-sync requirements.txt        # install AND remove, exact match
uv pip compile requirements.in -o requirements.txt     # same job, much faster

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["requests>=2.32", "pydantic>=2.8"]

[project.optional-dependencies]
dev = ["pytest>=8", "mypy>=1.11", "ruff"]

[project.scripts]
myapp = "myapp.cli:main"          # creates a `myapp` command on install

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

python -m pip install -e ".[dev]"     # project plus the dev extra

python -m pip install build twine
python -m build                       # writes dist/*.whl and dist/*.tar.gz
python -m twine check dist/*          # validate metadata and the README render
python -m twine upload --repository testpypi dist/*    # rehearse here first
python -m twine upload dist/*         # real PyPI

# uv, the command mapping most people need
uv venv                          # create .venv (add --python 3.13)
uv pip install -r requirements.txt   # pip-compatible, into .venv
uv pip compile requirements.in -o requirements.txt
uv add requests                  # edit pyproject.toml + update uv.lock + install
uv remove requests
uv lock                          # resolve to uv.lock
uv sync                          # make .venv match uv.lock exactly
uv sync --frozen                 # CI: install from the lock, never re-resolve
uv run pytest                    # run in the project env, syncing first
uv run --with rich python         # ephemeral extra dependency
uvx ruff check .                 # run a tool without installing it (uv tool run)
uv tool install ruff             # persistent CLI install, like pipx
uv python install 3.13           # manage interpreters, like pyenv
uv python list

# pipx, for command-line tools you want on PATH but not in your project
pipx install ruff
pipx install "httpie==3.2.4"
pipx inject poetry poetry-plugin-export   # add a dep to a tool's own env
pipx run cowsay hello                     # one-off, nothing installed
pipx list; pipx upgrade-all; pipx uninstall ruff

# poetry
poetry new myapp; poetry init         # scaffold or adopt
poetry add requests; poetry add --group dev pytest
poetry install; poetry install --no-root
poetry lock; poetry update
poetry run pytest; poetry shell
poetry build; poetry publish
poetry env info --path               # where the env actually lives

# pdm
pdm init; pdm add requests; pdm install; pdm run pytest; pdm lock

# conda, only when you need compiled non-Python dependencies
conda create -n myapp python=3.13 numpy
conda activate myapp; conda deactivate
conda env export > environment.yml
conda env create -f environment.yml
conda install -c conda-forge polars

# pyenv, interpreter versions
pyenv install 3.13.6; pyenv local 3.13.6; pyenv versions

which python python3 pip          # every match on PATH
python -c "import sys; print(sys.executable)"
python -c "import sys; print(sys.prefix, sys.base_prefix, sep='\n')"
# prefix != base_prefix means you ARE in a venv
echo "$VIRTUAL_ENV"
python -c "import sys; print(*sys.path, sep='\n')"
python -c "import requests; print(requests.__file__)"   # which copy loaded
python -m site                    # site-packages dirs, in order

python3 -m venv .venv && source .venv/bin/activate && python -m pip install pkg
pipx install some-cli-tool                        # if it is a CLI tool
python -m pip install --break-system-packages pkg # last resort, can break the OS

rm -rf .venv && uv venv && uv pip install -r requirements.txt