{"id":13815684,"url":"https://github.com/AndydeCleyre/zpy","last_synced_at":"2025-05-15T09:33:07.267Z","repository":{"id":41532638,"uuid":"208718711","full_name":"AndydeCleyre/zpy","owner":"AndydeCleyre","description":"Manage Python environments in Zsh, with uv or pip-tools","archived":false,"fork":false,"pushed_at":"2025-05-14T09:10:36.000Z","size":7136,"stargazers_count":91,"open_issues_count":14,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-14T10:36:02.525Z","etag":null,"topics":["completion","pip-tools","python","uv","venv","zsh","zsh-plugin"],"latest_commit_sha":null,"homepage":"https://andydecleyre.github.io/zpy/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AndydeCleyre.png","metadata":{"files":{"readme":"README.rst","changelog":"NEWS.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-09-16T05:43:03.000Z","updated_at":"2025-05-04T17:22:41.000Z","dependencies_parsed_at":"2023-09-22T23:00:05.816Z","dependency_job_id":"84f5e4cb-b9a3-4078-97b9-a4d6708d8010","html_url":"https://github.com/AndydeCleyre/zpy","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndydeCleyre%2Fzpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndydeCleyre%2Fzpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndydeCleyre%2Fzpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndydeCleyre%2Fzpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AndydeCleyre","download_url":"https://codeload.github.com/AndydeCleyre/zpy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254314031,"owners_count":22050156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["completion","pip-tools","python","uv","venv","zsh","zsh-plugin"],"created_at":"2024-08-04T04:03:52.785Z","updated_at":"2025-05-15T09:33:07.261Z","avatar_url":"https://github.com/AndydeCleyre.png","language":"Shell","funding_links":[],"categories":["Plugins","Shell"],"sub_categories":["ZSH on Windows"],"readme":"===\nzpy\n===\n-------------------------------------------------------\nManage Python environments in Zsh, with uv or pip-tools\n-------------------------------------------------------\n\n|ghpages| |reqs-ci| |container-ci|\n\n|container-alpine| |container-fedora| |container-ubuntu|\n\n|repo| |docsite| |contact|\n\n|logo|\n\n``zpy`` is a set of Zsh functions\nwrapping\nor uv__, or\npip-tools__\nand Python's venv module,\nfor the *simple* and *interactive* management of\nPython **virtual environments**,\n**dependency specifications**,\nand **isolated Python app installations**.\n\nNone of them should get in your way.\nAll have **thorough tab completion**.\n\n__ https://github.com/astral-sh/uv\n\n__ https://github.com/jazzband/pip-tools\n\nThey can generally replace pipenv, poetry, pipx, pipsi, virtualenvwrapper, etc.\n\n.. contents::\n\n|zpy-completions|\n\nGetting It\n----------\n\nThe short version of installation:\n\n- Install Python, Zsh, fzf__\n- Source this repo's ``zpy.plugin.zsh`` in your ``.zshrc``, or use a Zsh plugin manager to add ``andydecleyre/zpy``\n\n__ https://github.com/junegunn/fzf\n\nCheck out `the docs`__ for installation, explanation, and usage docs!\n\n__ https://andydecleyre.github.io/zpy/\n\nExamples\n--------\n\n- Install tools from PyPI or git, each with its own isolated venv:\n\n  .. code:: console\n\n    % pipz install uv tldr jello rich-cli yt-dlp 'visidata @ git+https://github.com/saulpw/visidata@develop'\n\n- Create a venv for the current folder (if necessary), activate it, and **sync** installed pkgs to match *all* ``requirements.txt`` lockfiles:\n\n  .. code:: console\n\n    % envin\n\n  . . . or sync packages to *particular* lockfiles:\n\n  .. code:: console\n\n    % envin dev-requirements.txt\n\n- **Add** a pkg to ``requirements.in``, **compile** a locked dep tree as ``requirements.txt``, and **sync** installed packages:\n\n  .. code:: console\n\n    % pipacs beautifulsoup4\n\n- **Compile** all ``(*-)requirements.in`` files, upgrading versions where possible, then **sync** to match:\n\n  .. code:: console\n\n    % pipcs -U\n\n- Inject \"loose\" requirements (as written in ``requirements.in``) into ``pyproject.toml``:\n\n  .. code:: console\n\n    % pypc\n\nThere are about 25 user-facing functions in total.\nFor details,\nsee the reference__ and the short guide__.\n\n__ https://andydecleyre.github.io/zpy/help_all/\n\n__ https://andydecleyre.github.io/zpy/start/\n\nThey are also available as subcommands to the \"supercommand\" ``zpy``;\n``envin`` is equivalent to ``zpy envin``, etc.\n\nBasic usage of ``envin`` and ``pipacs``:\n\n|envin-pipacs-gif|\n\nBasic usage of ``pipz``:\n\n|pipz-gif|\n\nTry it in a Container\n---------------------\n\nTry it in isolation with docker or podman with one of these commands:\n\n.. code:: console\n\n  $ docker run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-ubuntu:master\n  $ podman run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-ubuntu:master\n\nReplace \"ubuntu\" with \"alpine\" or \"fedora\" if you prefer.\n\nGuiding Ideas\n-------------\n\n.. image:: https://github.com/AndydeCleyre/zpy/raw/master/doc/src/img/flow.svg\n   :alt: Information flow diagram\n   :width: 100%\n\n- You should not have to manually specify the dependencies anywhere other than\n  ``*requirements.in`` files\n- Folks who want to use your code shouldn't have to install any new-fangled\n  less-standard tools (pipenv, poetry, pip-tools, zpy, etc.);\n  ``pip install -r *requirements.txt`` ought to be sufficient\n- It's nice to keep the venv folder *outside* of the project itself\n- Not every manageable project *needs* a ``pyproject.toml`` or to be packaged\n- Lockfiles are good\n- Tab completion is wonderful\n\n- These functions **don't**:\n\n  - need to be used exclusively\n  - need to be used by everyone on the same project\n  - do what mise__/pyenv__/asdf-vm__ or flit__ do best (but do work with them if you choose)\n  - *conflict* with anything else your team cares to do with your code;\n    If they can be a friendlier neighbor to your workflows, file an issue__\n\n__ https://github.com/jdx/mise\n\n__ https://github.com/pyenv/pyenv\n\n__ https://asdf-vm.com\n\n__ https://flit.readthedocs.io/en/latest/\n\n__ https://github.com/AndydeCleyre/zpy/issues\n\nKnown Issues\n------------\n\nFunctions ``pipacs``, ``pipac``, ``pipcs``, and ``pipc`` allow forwarding arguments directly\nto ``pip-compile``, or ``uv pip compile`` when ``uv`` is installed.\n\nThere are currently two problems with this when ``uv`` is used:\n\n- Tab completion of those arguments, even when ``uv`` tab completions are installed, will fail.\n  If it bothers you, please add a 👍 on\n  `their existing issue`__.\n- When the options passed are intended to override ones already passed internally,\n  the command will fail.\n  If this bothers you, please add a 👍 on\n  `their existing issue`__.\n\n__ https://github.com/astral-sh/uv/issues/3249\n\n__ https://github.com/astral-sh/uv/issues/3248\n\n.. |repo| image:: https://img.shields.io/github/size/andydecleyre/zpy/zpy.plugin.zsh?logo=github\u0026label=Code\u0026color=blueviolet\n   :alt: Plugin file size in bytes\n   :target: https://github.com/andydecleyre/zpy\n\n.. |container-alpine| image:: https://img.shields.io/badge/Container-Quay.io-green?logo=alpine-linux\n   :alt: Demo container - Alpine Linux\n   :target: https://quay.io/repository/andykluger/zpy-alpine\n\n.. |container-fedora| image:: https://img.shields.io/badge/Container-Quay.io-green?logo=red-hat\n   :alt: Demo container - Fedora\n   :target: https://quay.io/repository/andykluger/zpy-fedora\n\n.. |container-ubuntu| image:: https://img.shields.io/badge/Container-Quay.io-green?logo=ubuntu\n   :alt: Demo container - Ubuntu\n   :target: https://quay.io/repository/andykluger/zpy-ubuntu\n\n.. |container-ci| image:: https://github.com/AndydeCleyre/zpy/actions/workflows/ctnrs.yml/badge.svg?branch=develop\n   :alt: Demo containers - GitHub Actions\n   :target: https://github.com/AndydeCleyre/zpy/actions/workflows/ctnrs.yml\n\n.. |reqs-ci| image:: https://github.com/AndydeCleyre/zpy/actions/workflows/reqs.yml/badge.svg\n   :alt: Bump PyPI requirements - GitHub Actions\n   :target: https://github.com/AndydeCleyre/zpy/actions/workflows/reqs.yml\n\n.. |contact| image:: https://img.shields.io/badge/Contact-Telegram-blue?logo=telegram\n   :alt: Contact developer on Telegram\n   :target: https://t.me/andykluger\n\n.. |docsite| image:: https://readthedocs.org/projects/zpy/badge/\n   :alt: Documentation Status\n   :target: https://zpy.readthedocs.io/en/latest/\n\n.. |ghpages| image:: https://github.com/AndydeCleyre/zpy/actions/workflows/gh-pages.yml/badge.svg?branch=master\n   :alt: Build GitHub Pages\n   :target: https://andydecleyre.github.io/zpy/\n\n.. |logo| image:: https://github.com/AndydeCleyre/zpy/blob/assets/zpy-logo.png?raw=true\n   :alt: zpy logo\n   :width: 160px\n\n.. |zpy-completions| image:: https://user-images.githubusercontent.com/1787385/172661113-7a2c6670-e716-491e-8db4-c005fef8455b.png\n   :alt: zpy supercommand completions\n   :width: 800px\n\n.. |envin-pipacs-gif| image:: https://github.com/AndydeCleyre/zpy/blob/assets/envin_pipacs.gif?raw=true\n   :alt: Animated envin and pipacs demo\n   :width: 800px\n\n.. |pipz-gif| image:: https://github.com/AndydeCleyre/zpy/blob/assets/pipz.gif?raw=true\n   :alt: Animated pipz demo\n   :width: 800px\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAndydeCleyre%2Fzpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAndydeCleyre%2Fzpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAndydeCleyre%2Fzpy/lists"}