Introduction

What?

zpy is a set of Zsh functions, mostly wrapping pip-tools or uv, for the simple and practical management of Python virtual environments, dependency specifications, and isolated Python app installation.

You may find it a suitable alternative to poetry, pipenv, pipx, or unaided pip-tools or uv.

There's a focus on use of good old requirements.txt files, and extensive tab completion assistance.

Read below for some rationale, check the readme for some quick-start examples, or just get started with the short guide.

Why?

You may not like something about the way alternatives behave

You may find poetry or pipenv a good fit, and that's ok. I have personally found them to conflict with my needs and preferences:

• both introduce new-syntax files
• neither can do what pipx does
• poetry is a bit rigid, only working with installable packages as projects
• pipenv is problematically nosy and weird sometimes, e.g. using unrelated files above the current folder without consent
• neither fully embrace the rich completions and other features that Zsh offers

I have had only good experience with pipx, and replacing its features here was not an initial goal. I just couldn't resist when the other functions provided components for a transparent pipx substitute, with excellent tab completion.

requirements.txt is good!

The requirements.txt format is:

• maximally compatible with basic Python tools (pip install -r)
• an "old" standard but recognized by modern tooling as well
• friendly to line-oriented shell tools and manipulation
• simple, readable, concise
• due to all the above, compatible with a heterogeneous dev setup; no strict need for all devs to use a single tooling or workflow
• fully capable as a lockfile
• friendly to VCS tracking

pip-tools is good!

It's a great project and a practical tool. The model of requirements.in -> requirements.txt is strong. I appreciate its ability to support a variety of practices, without a fight. There's always more work to do be done there, so please don't be shy to squash some bugs!

uv is also good!

While in some ways less flexible than pip-tools, uv is fast, sensible, features clear and concise output, and is a practical replacement for both pip-tools and Python's venv module.

Zsh is fantastic!

Zsh provides a powerful toolset for the interactive shell and scripting, and some unique and beautiful syntax, and I wanted to explore that. And the interactive shell seems a proper place from which to coordinate Python virtual environment related activities.

Directional Flow of Dependency Specification

While you don't have to be a believer in order to make use of zpy functions, there is a directional flow of data that is expected and supported by their design.

The idea is that dependencies should only be manually edited in requirements.in files, from which requirements.txt lockfiles and pyproject.toml files may be generated.

Then virtual environments can be produced or adjusted to match the requirements.txt specifications.

For example:

It's basically the pip-tools model but with pyproject.toml as an output rather than input.

But your workflow does not need to match that to make use of many of these functions; you can also generate lockfiles from pyproject.toml, setup.cfg, or setup.py files, or even avoid generating lockfiles altogether.