pyruve

pyruve automatically activates the nearest Python virtual environment when you change directories. It deactivates the environment after you leave its project tree.

pyruve supports POSIX operating systems with the standard <venv>/bin layout. It integrates with these shells:

• Bash
• Fish
• Tcsh
• Zsh

Windows shells are not supported.

Install

Install the current release from crates.io:

cargo install pyruve

On glibc-based Linux, an optional static local build can reduce process startup overhead:

RUSTFLAGS='-C target-feature=+crt-static' cargo install --force pyruve

The static build is platform-specific. Use the standard installation command on other systems.

Ensure that Cargo's binary directory is in PATH. It is normally $HOME/.cargo/bin.

Then add one initializer to your shell configuration.

Bash

Add this line to .bashrc:

source <(pyruve shell bash)

Fish

Add this line to ~/.config/fish/config.fish:

pyruve shell fish | source

Zsh

Add this line to .zshrc:

eval "$(pyruve shell zsh)"

Tcsh

Add these lines to .tcshrc:

eval "`pyruve shell tcsh`"
_pyruve_apply

Restart the shell after installation or upgrade.

Behavior

On each directory change, pyruve searches the current directory and its ancestors. It uses the nearest matching virtual environment.

By default, these directories match:

• venv
• .venv
• <project>-venv
• <project>_venv
• <project>-.venv
• <project>_.venv

Nested projects can have independent environments. Moving from an outer project into a nested project activates the nested environment.

Paths containing spaces or apostrophes are supported. Activation paths containing newline characters are rejected. Returned activation paths are sourced directly and are never passed to eval. Tcsh uses eval only to invoke the fixed deactivate alias created by activate.csh.

Configuration

PYRUVE_VENV_DIRS contains a comma-separated list of base directory names:

export PYRUVE_VENV_DIRS='venv,.venv,virtenv,.virtenv'

PYRUVE_DELIMITERS contains delimiters for combined names:

export PYRUVE_DELIMITERS='-,_'

PYRUVE_COMBINE_DIRS controls combined names such as project-venv. The values true, t, 1, and on enable this behavior. Any other value disables it.

Security

pyruve sources the activation script found in a matching environment directory. Activation scripts are executable shell code.

Use pyruve only in project trees that you trust. The tool verifies the script path, but it does not inspect or sandbox script contents.

Compatibility

The repository tests Bash, Fish, Tcsh, and Zsh with real Python environments. CI runs the shell integration suite in Debian Bookworm and Alpine 3.24 containers. CI builds the crate with stable Rust; no minimum supported Rust version is promised.

Other shells need explicit integrations because environment mutation is shell-specific. Nushell and PowerShell need structured environment updates, so they are not syntax-only additions.

Development

Run the Rust checks locally:

cargo fmt --all -- --check
cargo test --locked
cargo clippy --all-targets --locked -- -D warnings

The shell integration test also requires Bash, Fish, Tcsh, Zsh, and python3-venv:

cargo build --locked
tests/shell_integration.sh target/debug/pyruve