Automatically activate Poetry environments when changing directories in Zsh
This plugin automatically detects and activates Python Poetry virtual environments when you change into a Poetry project directory, and deactivates them when you leave. It's fast, efficient, and highly configurable.
Oh My Zsh includes a built-in poetry-env plugin that provides similar basic functionality. While both plugins handle automatic Poetry environment activation, poetry-auto-zsh offers several advantages:
- Performance: Uses caching to avoid slow
poetry env infocalls on every directory change - Features: Provides a comprehensive CLI interface for managing auto-activation
- Configurability: Offers environment variables and commands for fine-tuned control
- Integration: Better handles edge cases and interactions with other tools like direnv
- User experience: Adds project name detection for prompt customization
If you just need basic Poetry environment activation, the built-in plugin works fine. Choose poetry-auto-zsh when you need better performance, more features, or finer control.
- Automatic activation/deactivation of Poetry environments on directory change
- High performance with smart caching to avoid slow
poetry env infocalls - Compatible with direnv and other environment managers
- Fully configurable with options to disable/enable different features
- CLI management tool with tab completions to control all aspects of auto-activation
- Oh My Zsh compatible but works with any zsh setup or plugin manager
Using Oh My Zsh
git clone https://github.com/kelp/poetry-auto-zsh ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/poetry-autoThen add poetry-auto to your plugins array in .zshrc:
plugins=(... poetry-auto)Using zplug
zplug "kelp/poetry-auto-zsh"Using zinit
zinit light kelp/poetry-auto-zshgit clone https://github.com/kelp/poetry-auto-zsh ~/.zsh/poetry-auto-zsh
echo 'source ~/.zsh/poetry-auto-zsh/poetry-auto.plugin.zsh' >> ~/.zshrcOnce installed, poetry-auto-zsh works immediately without any configuration. It will:
- Automatically detect Poetry projects (directories with
pyproject.tomland[tool.poetry]section) - Activate the appropriate virtual environment when you enter a project directory
- Deactivate the environment when you leave the project directory
The plugin provides a poetry-auto command with tab completion:
# Show current status
poetry-auto status
# Disable auto-activation
poetry-auto disable
# Enable auto-activation
poetry-auto enable
# Toggle verbose output (for debugging)
poetry-auto verbose
# Clear the environment cache
poetry-auto cache clearYou can configure the plugin by setting these variables in your .zshrc (before sourcing the plugin):
# Disable auto-activation
export POETRY_AUTO_DISABLE=1
# Enable verbose output
export POETRY_AUTO_VERBOSE=1
# Change cache directory
export POETRY_AUTO_CACHE_DIR="$HOME/.cache/custom-poetry-path"poetry-auto-zsh sets a POETRY_PROJECT environment variable with the active project name. You can use this in your prompt:
# For powerlevel10k
POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(... virtualenv)
# For a custom prompt
function poetry_prompt_info() {
[[ -n "$POETRY_PROJECT" ]] && echo " 📜($POETRY_PROJECT)"
}
PS1+='$(poetry_prompt_info)'The plugin uses smart caching to avoid repeated slow calls to poetry env info. Once a virtual environment is activated, its path is cached using a directory hash, making future activations nearly instantaneous.
The plugin includes a test suite that can be run using the Makefile:
make test # Run tests
make lint # Check syntax
make all # Run both tests and linting
make clean # Clean up test artifactsThe tests are automatically run on GitHub Actions for all pull requests and pushes to the main branch.
MIT © Travis Cole
Note: This plugin was largely developed with assistance from Claude Code, Anthropic's AI coding assistant.