Python packaging, environment and dependency management

2.1 pip + venv

venv works, for all that I would like it to work more smoothly. It is a built-in Python virtual environment system in Python 3, replacing virtualenv which we still find documented about the place. It doesn’t support Python 2 (which virtualenv did, but also let Python 2 go unless someone is paying you money to keep a grip on it) but fixes various problems, e.g. it supports framework Python on macOS which is important for GUIs, and is covered by the Python docs in the Python virtual environment introduction. venv is a good default choice, widely supported and adequate, if not awesome, workflow.

# Create venv in the current folder
python3 -m venv ./venv --prompt some_arbitrary_name
# or if we want to use system packages:
python3 -m venv ./venv --prompt some_arbitrary_name --system-site-packages
# Use venv from fish OR
source ./venv/bin/activate.fish
# Use venv from bash
source ./venv/bin/activate

Once we have made a virtualenv we can fill it with dependencies, which involves the other tool, pip. pip is the default Python package installer. It is best invoked as

python -m pip install package_name

Note that we can use pip to install packages outside of a virtual environment. It will happily execute outside an active venv without complaint. However, doing so does wildly inconsistent things across different platforms and I have no idea what it would be good for, apart from creating confusing errors and introducing bugs. Depending on which platform I am on, it will either work, fail, or introduce subtle problems that I will notice later when other things break. I have not found a use case for installing packages outside of a venv in more than a decade of Python programming. Maybe in a docker container or something? If I find myself wishing to do a global Python package installation, what I probably want is pipx, which creates a global command (but still gives that command its own isolated environment so it can operate predictably.)

Hereafter I assume we are in an active venv.

I always begin by upgrading pip itself and installing wheel which is some bit of installation infrastructure which is helpful in practice. Thereafter everything else should install more correctly except when it doesn’t.

python -m pip install --upgrade pip wheel

To snapshot dependencies in requirement.txt:

python -m pip freeze > requirements.txt

I do not recommend actually using the freeze command except as a first draft. It is way too specific and includes very precise version numbers and obscure, locally-specific sub-dependencies. Best keep a tally of the actual hard dependencies and let pip sort out the details.

To restore dependencies from a requirements.txt,

python -m pip install -r requirements.txt

Version specification in requirements.txt looks something like this:

MyProject
YourProject == 1.3
SomeProject >= 1.2, < 2.0
SomeOtherProject[foo, bar]
OurProject ~= 1.4.2
TheirProject == 5.4 ; python_version < '3.8'
HerProject ; sys_platform == 'win32'
requests [security] >= 2.8.1, == 2.8.* ; python_version < "2.7"

The ~= is a handy lazy shortcut; it permits point releases, but not minor releases, so e.g. ~=1.3.0 will also satisfy itself with version 1.3.9 but not 1.4.0.

3.1 conda

A parallel system to pip. Designed to do all the work of installing especially Python software with hefty compiled dependencies.

There are two parts here with two separate licences:

1. the Anaconda Python distribution
2. the conda Python package manager.

I am slightly confused about how these two relate. The distinction is important, since licensing Anaconda proper can be expensive. See, e.g.

• Anaconda is not free for commercial use (any more) so what are the alternatives?
• Conda/Anaconda no longer free to use?
• See also mamba or Pixi below, which aim to reduce licensing risk by reimplementing the more licensing-vulnerable parts of the Anaconda ecosystem, plus also be better in other ways.
• Can I install an entirely non-Anaconda Python distribution through the conda package manager?

Some things that are (or were?) painful to install by pip are painless via conda. Contrariwise, some things that are painful to install by conda are easy by pip.

I recommend working out which pain points are worse in this system is a complicated calculation by trial and error. If conda does not bring substantial value, choose pip. Sometimes it would be worth the administrative burden of understanding conda’s current licensing and future licensing risks, but it would have to be a strong win.

This is an updated recommendation; previously I preferred conda — pip used to be much worse, and Anaconda’s licensing used to be less restrictive.

bash Miniconda3-latest-Linux-x86_64.sh
# login/logout here
# or do something like `exec bash -` if you are fancy
# Less aggressive conda
conda config --set auto_activate_base false
# conda for fish users
conda init fish

curl -L -O https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh
bash Mambaforge-$(uname)-$(uname -m).sh

conda install pytables=3.2
conda install pyqt=4

source (conda info --root)/etc/fish/conf.d/conda.fish

conda init fish

conda install nb_conda_kernels

conda env export > environment.yml

conda env create --file environment.yml

conda clean --all --yes

conda config --add pkgs_dirs /SOME/OTHER/PATH/.conda

chmod a-rwx ~/.conda

conda create -n pynomkl python nomkl

conda config --set env_prompt '({name})'
conda env create --prefix ./env/myenv --file environment_linux.yml
conda activate ./env/myenv

conda config --set env_prompt '${name}$'

env_prompt: ({name})

3.2 Poetry

No! wait! The new new new hipness is poetry. All the other previous hipnesses were not the real eternal ultimate hipness that transcends time. I know we said this every previous time a new python packaging system came out, but this time it’s real and our love will last forever ONO.

⛔️⛔️UPDATE⛔️⛔️: Surprise twist: it turns out this love was not actually quite as eternal as it seemed. Lovely elegant design does not make up for the fact that the project is logjammed and broken in various ongoing ways; see Issue #4595: Governance—or, “what do we do with all these pull requests?”. It might be usable if your needs are modest or you are prepared to jump into the project discord, which seems to be where the poetry hobbyists organise, but since I want to use this project merely incidentally, as a tool to develop something else, hobbyist level of engagement is not something I can participate in. poetry is not ready for prime-time.

Note also that poetry is having difficulty staying current with local versions, as made famous by CUDA-supporting packages. There is an example of the kind of antics that make it work below.

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

From the introduction:

Packaging systems and dependency management in Python are rather convoluted and hard to understand for newcomers. Even for seasoned developers it might be cumbersome at times to create all files needed in a Python project: setup.py, requirements.txt, setup.cfg, MANIFEST.in and the newly added Pipfile.

So I wanted a tool that would limit everything to a single configuration file to do: dependency management, packaging and publishing.

It takes inspiration in tools that exist in other languages, like composer (PHP) or cargo (Rust).

And, finally, I started poetry to bring another exhaustive dependency resolver to the Python community apart from Conda’s.

What about Pipenv?

In short: I do not like the CLI it provides, or some of the decisions made, and I think we can make a better and more intuitive one.

Editorial side-note: Low-key dissing on similarly dysfunctional, competing projects is an important part of Python packaging.

Lazy install is via this terrifying command line (do not run if you do not know what this does):

curl -sSL https://install.python-poetry.org | python -

Poetry could be regarded as a similar thing to pipenv, in that it (per default, but not necessarily) manages the dependencies in a local venv. It has a much more full-service approach than systems built on pip. For example, it has its own dependency resolver, which makes use of modern dependency metadata but also will work with previous dependency specifications by brute force if needed. It separates specified dependencies from the ones that it contingently resolves in practice, which means that the dependencies seem to transport much better than conda, which generally requires you to hand-maintain a special dependency file full of just the stuff you actually wanted. In practice the many small conveniences and thoughtful workflow are helpful. For example, it will set up the current package for developing per default so that imports work as similarly as possible across this local environment and when it is distributed to users.

poetry config virtualenvs.create true
poetry config virtualenvs.in-project true  # local venvs are easier for my brain.

rm -r ~/Library/Caches/pypoetry/cache
rm -r ~/Library/Caches/pypoetry/artifacts

poetry shell -C $PWD/.venv

poetry env use $(pyenv which python)

[tool.poetry.dependencies]
python = "^3.10"
numpy = "^1.23.2"
torch = { version = "1.12.1", source="torch"}
torchaudio = { version = "0.12.1", source="torch"}
torchvision = { version = "0.13.1", source="torch"}

[[tool.poetry.source]]
name = "torch"
url = "https://download.pytorch.org/whl/cu116"
secondary = true

poetry source add --priority=supplemental torch https://download.pytorch.org/whl/cu118
poetry add torch==2.0.1+cu118 --source torch

poetry add "https://download.pytorch.org/whl/cu118/torch-2.0.0%2Bcu118-cp310-cp310-linux_x86_64.whl"

poetry run python -m ipykernel install --user --name pymedphys

[tool.poetry.group.dev]  # This part can be left out
optional = true

[tool.poetry.group.dev.dependencies]
ipdb = "~0.13.13"
ipykernel = "~6.29.4"
scalene = "~1.5.41"

poetry install --with dev

3.3 pipenv

⛔️⛔️UPDATE⛔️⛔️: Note that the pipenv system does not support “local versions” and thus in practice cannot be used for machine learning applications. This project is dead to me. (Bear in mind that my opinions about will become increasingly outdated depending on when you read this.)

venv has a higher-level, er, …wrapper (?) interface (?) called pipenv.

Pipenv is a production-ready tool that aims to bring the best of all packaging worlds to the Python world. It harnesses Pipfile, pip, and virtualenv into one single command.

I switched to pipenv from poetry because it looked like it might be less chaos than poetry. I think it is, although not by much.

HOWEVER, it is still pretty awful for my use case. TBH, I would just use plain pip and requirements.txt which, while primitive and broken, is at least broken and primitive in a well-understood way.

At the time of writing, the pipenv website was 3 weeks into an outage, because dependency management is a quagmire of sadness and comically broken management with terrible Bus factor. However, the backup docs site is semi-functional, albeit too curt to be useful and AFAICT outdated. The documentation site inside GitHub is readable. See also an introduction showing pipenv and venv used together.

The dependency resolver is, as the poetry devs point out, broken in its own special ways. The procedure to install modern ML frameworks, for example, is gruelling.

For my system, important settings are

export WORKON_HOME=~/.venvs

To get the venv inside the project (required for sanity in my HPC) I need the following:

export PIPENV_VENV_IN_PROJECT=1

Pipenv will automatically load dotenv files which is a nice touch.

3.4 Zipapp/.pyz

Python supports zipped executable code bundles, under the name zipapp. Does that mean the problems are all solved with regard to Python packaging? No, because not only can it not bundle binary dependencies, but it still needs the system Python interpreter to exist and be compatible with the target system. Still, a cool trick that is occasionally useful for people who are not me.

3.5 pipx

Pro tip: pipx:

pipx is made specifically for application installation, as it adds isolation yet still makes the apps available in your shell: pipx creates an isolated environment for each application and its associated packages.

That is, pipx is an application that installs global applications for you.

3.6 Rye

• astral-sh/rye: a Hassle-Free Python Experience
• Rye

A nifty system largely subsumed into uv.

3.7 PDM

PDM

is a modern Python package and dependency manager supporting the latest PEP standards. But it is more than a package manager. It boosts your development workflow in various aspects. The most significant benefit is it installs and manages packages in a similar way to npm that doesn’t need to create a virtualenv at all!

Feature highlights:

• Opt-in PEP 582 support, no virtualenv involved at all.
• Simple and fast dependency resolver, mainly for large binary distributions.
• A PEP 517 build backend.
• PEP 621 project metadata.
• Flexible and powerful plug-in system.
• Versatile user scripts.
• Opt-in centralized installation cache like pnpm.

Update: PEP582 was rejected

3.8 Flit

Why use Flit?

Make the easy things easy and the hard things possible is an old motto from the Perl community. Flit is entirely focused on the easy things part of that, and leaves the hard things up to other tools.

Specifically, the easy things are pure Python packages with no build steps (neither compiling C code, nor bundling Javascript, etc.). The vast majority of packages on PyPI are like this: plain Python code, with maybe some static data files like icons included.

It’s easy to underestimate the challenges involved in distributing and installing code, because it seems like you just need to copy some files into the right place. There’s a whole lot of metadata and tooling that has to work together around that fundamental step. But with the right tooling, a developer who wants to release their code doesn’t need to know about most of that.

What, specifically, does Flit make easy?

• flit init helps you set up the information Flit needs about your package.
• Subpackages are automatically included: you only need to specify the top-level package.
• Data files within a package directory are automatically included. Missing data files has been a common packaging mistake with other tools.
• The version number is taken from your package’s __version__ attribute, so that always matches the version that tools like pip see.
• flit publish uploads a package to PyPI, so you don’t need a separate tool to do this.

Setuptools, the most common tool for Python packaging, now has shortcuts for many of the same things. But it has to stay compatible with projects published many years ago, which limits what it can do by default.

3.9 Hatch

Hatch

Hatch is a modern, extensible Python project manager.

Features:

• Standardised build system with reproducible builds by default
• Robust environment management with support for custom scripts
• Easy publishing to PyPI or other indexes
• Version management
• Configurable project generation with sane defaults
• Responsive CLI, ~2-3x faster than equivalent tools

4.1 Spack

Supercomputing dep manager spack has Python-specific support.

PyPI has hundreds of thousands of packages that are not yet in Spack, and pip may be a perfectly valid alternative to using Spack. The main advantage of Spack over pip is its ability to compile non-Python dependencies. It can also build cythonized versions of a package or link to an optimised BLAS/LAPACK library like MKL, resulting in calculations that run orders of magnitudes faster. Spack does not offer a significant advantage over other Python-management systems for installing and using tools like flake8 and sphinx. But if you need packages with non-Python dependencies like numpy and scipy, Spack will be very valuable to you.

Anaconda is another great alternative to Spack, and comes with its own conda package manager. Like Spack, Anaconda is capable of compiling non-Python dependencies. Anaconda contains many Python packages that are not yet in Spack, and Spack contains many Python packages that are not yet in Anaconda. The main advantage of Spack over Anaconda is its ability to choose a specific compiler and BLAS/LAPACK or MPI library. Spack also has better platform support for supercomputers, and can build optimised binaries for your specific microarchitecture.

4.2 Meson

• meson-python uses The Meson Build system for Python. Is that… good?

5.1 scaffolding and templating

Generating all those files is boring. The Python packaging ecosystem has a number of tools to automate it.

5.2 Documenting my package

Here are two famous options. I have used Sphinx and it is adequate, but has its own markup language which the world outside of Python does not use.

• Sphinx
• MkDocs

6.1 pyenv

pyenv is the core tool of an ecosystem which eases and automates switching between Python versions. Manages Python and thus implicitly can be used as a manager for all the other managers. The new new hipness, at least for platforms other than Windows, where it does not work.

BUT WHO MANAGES THE VIRTUALENV MANAGER MANAGER? Also, what is going on in this ecosystem of bits? Logan Jones explains:

• pyenv manages multiple versions of Python itself.
• virtualenv/venv manages virtual environments for a specific Python version.
• pyenv-virtualenv manages virtual environments across varying versions of Python.

Anyway, pyenv compiles a custom version of Python and as such is extremely isolated from everything else. An introduction with emphasis on my area: Intro to Pyenv for Machine Learning.

#initial pyenv install
pyenv init
# install a specific Python version
pyenv install 3.8.13
# ensure we can find that version
pyenv rehash
# switch to that version
pyenv shell 3.8.13

Of course, because this is adjacent to Python packaging, it is infected with the same brainworms. Everything immediately becomes complicated and confusing when I try to interact with the rest of the ecosystem, e.g.,

pyenv-virtualenvwrapper is different from pyenv-virtualenv, which provides extended commands like pyenv virtualenv 3.4.1 project_name to directly help out with managing virtualenvs. pyenv-virtualenvwrapper helps in interacting with virtualenvwrapper, but pyenv-virtualenv provides more convenient commands, where virtualenvs are first-class pyenv versions, that can be (de)activated. That’s to say, pyenv and virtualenvwrapper are still separated while pyenv-virtualenv is a nice combination.

Huh. I am already too bored to think. However, I did work out a command which installed a pyenv tensorflow with an isolated virtualenv:

brew install pyenv pyenv-virtualenv
pyenv install 3.8.6
pyenv virtualenv 3.8.6 tf2.4
pyenv activate tf2.4
pip install --upgrade pip wheel
pip install 'tensorflow-probability>=0.12' 'tensorflow<2.5' jupyter

For fish shell I needed to add some special lines to config.fish:

set -x PYENV_ROOT $HOME/.pyenv
set -x PATH $PYENV_ROOT/bin $PATH
## fish <3.1
# status --is-interactive; and . (pyenv init -|psub)
# status --is-interactive; and . (pyenv virtualenv-init -|psub)
## fish >=3.1
status --is-interactive; and pyenv init - | source
status --is-interactive; and pyenv virtualenv-init - | source

For bash/zsh (resp. .bashrc/.zshrc) it is as follows:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"