pyhop

A CLI to inspect and activate Python environments across venv, poetry, uv, conda, pyenv, and pixi.

Default invocation (pyhop with no arguments) opens an fzf picker to choose an environment, prints the activation shell snippet to stdout, then quits. A small shell function in your rc does eval on the snippet — the CLI never replaces your shell.

Why

If you have many Python projects, you likely have many envs: some via python -m venv, some via poetry, some via uv, some via conda, some via pyenv, some via pixi. Switching between them is fiddly — each has its own activation command, its own naming, its own quirks. pyhop unifies them: one command, one picker, one activation.

Installation

pip install pyhop

Or with pipx (recommended for CLI tools):

pipx install pyhop

Or with uv:

uv tool install pyhop

Shell setup

Add one of these to your shell rc (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish, ~/.config/nushell/config.nu, or $PROFILE):

# bash / zsh
pyhop() { eval "$(command pyhop "$@")"; }

# fish
function pyhop; eval (command pyhop $argv); end

# nushell — uses def-env + temp file + source so let-env calls mutate the
# caller's env (the standard nushell idiom, also used by zoxide / atuin).
def-env pyhop [...rest: string] {
    let tmp = (mktemp --suffix .nu)
    ^pyhop ...rest | save --force $tmp
    source $tmp
    rm $tmp
}

# PowerShell
function pyhop { & pyhop @args | Out-String | Invoke-Expression }

Now pyhop with no arguments opens fzf, you pick an env, and your shell activates it.

Commands

Command	Description
pyhop	Open fzf picker, activate the selected env (default)
pyhop use [name]	Activate a specific env by name (skips fzf)
pyhop check	Inspect the currently-active env
pyhop list	List all detected envs (add --json for scripts)
pyhop info <env>	Show details of one env
pyhop create <name>	Create a new env (--python, --manager)
pyhop remove <env>	Remove an env (asks for confirmation; --yes to skip)
pyhop doctor [--fix]	Diagnose issues across all envs
pyhop --version	Show pyhop version

Supported env managers

• system Python
• python -m venv / virtualenv (also auto-detects uv via uv.lock)
• poetry
• uv
• conda / mamba / micromamba
• pyenv
• pixi

Configuring project roots

pyhop discovers venvs by walking configurable project roots. By default it walks your current working directory. Set $PYHOP_PROJECT_ROOTS to point at other trees (colon-separated on Unix, semicolon-separated on Windows):

export PYHOP_PROJECT_ROOTS="$HOME/projects:$HOME/code:$HOME/work"

pyhop will scan up to 4 directory levels deep, skipping node_modules, .git, __pycache__, .tox, .nox, dist, build, .eggs, and site-packages.

Optional: fzf

pyhop uses fzf for the picker. If fzf is not installed, pyhop falls back to a numbered list (you type the number to choose). Install fzf for the best experience:

# macOS
brew install fzf

# Ubuntu / Debian
sudo apt install fzf

# Arch
sudo pacman -S fzf

# Windows (scoop)
scoop install fzf

Development

git clone https://github.com/azinsharaf/pyhop
cd pyhop
uv venv .venv --python 3.12
uv pip install -e ".[dev]" --python .venv
pre-commit install
pytest

License

MIT — see LICENSE.