Auto Uv Env

auto-uv-env 🐍

[](https://opensource.org/licenses/MIT) [](https://github.com/astral-sh/uv)

Automatic UV-based Python virtual environment management for your shell.

`auto-uv-env` watches directory changes, discovers the nearest `pyproject.toml`, creates a project-local virtual environment with `uv`, and activates/deactivates it automatically.

Architecture Overview

+-------------------------+      --check-safe       +-------------------------+
| shell hook              |------------------------>| auto-uv-env             |
| bash/zsh/fish adapter   |<------------------------| directive producer      |
+------------+------------+      KEY=VALUE lines    +------------+------------+
             |                                                   |
             | applies directives                               | reads pyproject.toml
             v                                                   | validates venv name
      +------+--------------------------+                        |
      | source/deactivate virtualenv    |                        |
      | uv python install / uv venv     |<-----------------------+
      +---------------------------------+

Quick Start

1) Install UV

curl -LsSf https://astral.sh/uv/install.sh | sh

2) Install auto-uv-env

Installer script:

curl -LsSf https://auto-uv-env.ashwch.com/install.sh | sh

Homebrew:

brew tap ashwch/tap
brew install auto-uv-env

3) Add shell integration

Zsh (`~/.zshrc`):

source $(brew --prefix)/share/auto-uv-env/auto-uv-env.zsh
# or: source /usr/local/share/auto-uv-env/auto-uv-env.zsh

Bash (`~/.bashrc`):

source $(brew --prefix)/share/auto-uv-env/auto-uv-env.bash
# or: source /usr/local/share/auto-uv-env/auto-uv-env.bash

Fish (`~/.config/fish/config.fish`):

source (brew --prefix)/sh