zpy

Manage Python environments in Zsh, with uv or pip-tools

zpy is a set of Zsh functions wrapping or uv, or pip-tools and Python's venv module, for the simple and interactive management of Python virtual environments, dependency specifications, and isolated Python app installations.

None of them should get in your way. All have thorough tab completion.

They can generally replace pipenv, poetry, pipx, pipsi, virtualenvwrapper, etc.

Contents

• Getting It
• Examples
• Try it in a Container
• Guiding Ideas
• Known Issues

Getting It

The short version of installation:

• Install Python, Zsh, fzf
• Source this repo's zpy.plugin.zsh in your .zshrc, or use a Zsh plugin manager to add andydecleyre/zpy

Check out the docs for installation, explanation, and usage docs!

Examples

• Install tools from PyPI or git, each with its own isolated venv:

  % pipz install uv tldr jello rich-cli yt-dlp 'visidata @ git+https://github.com/saulpw/visidata@develop'

• Create a venv for the current folder (if necessary), activate it, and sync installed pkgs to match all requirements.txt lockfiles:

  % envin

  . . . or sync packages to particular lockfiles:

  % envin dev-requirements.txt

• Add a pkg to requirements.in, compile a locked dep tree as requirements.txt, and sync installed packages:

  % pipacs beautifulsoup4

• Compile all (*-)requirements.in files, upgrading versions where possible, then sync to match:

  % pipcs -U

• Inject "loose" requirements (as written in requirements.in) into pyproject.toml:

  % pypc

There are about 25 user-facing functions in total. For details, see the reference and the short guide.

They are also available as subcommands to the "supercommand" zpy; envin is equivalent to zpy envin, etc.

Basic usage of envin and pipacs:

Basic usage of pipz:

Try it in a Container

Try it in isolation with docker or podman with one of these commands:

$ docker run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-ubuntu:master
$ podman run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-ubuntu:master

Replace "ubuntu" with "alpine" or "fedora" if you prefer.

Guiding Ideas

• You should not have to manually specify the dependencies anywhere other than *requirements.in files
• Folks who want to use your code shouldn't have to install any new-fangled less-standard tools (pipenv, poetry, pip-tools, zpy, etc.); pip install -r *requirements.txt ought to be sufficient
• It's nice to keep the venv folder outside of the project itself
• Not every manageable project needs a pyproject.toml or to be packaged
• Lockfiles are good
• Tab completion is wonderful
• These functions don't:
  • need to be used exclusively
  • need to be used by everyone on the same project
  • do what mise/pyenv/asdf-vm or flit do best (but do work with them if you choose)
  • conflict with anything else your team cares to do with your code; If they can be a friendlier neighbor to your workflows, file an issue

Known Issues

Functions pipacs, pipac, pipcs, and pipc allow forwarding arguments directly to pip-compile, or uv pip compile when uv is installed.

There are currently two problems with this when uv is used:

• Tab completion of those arguments, even when uv tab completions are installed, will fail. If it bothers you, please add a 👍 on their existing issue.
• When the options passed are intended to override ones already passed internally, the command will fail. If this bothers you, please add a 👍 on their existing issue.