AutoActivator

How it works

When you change directories, AutoActivator scans the current directory — and up to your home directory — for a virtual environment. Finds one? Activated. Leave the project tree? Deactivated. That's the whole contract.

• Cached. Found venvs are cached per directory, so repeated visits cost nothing.
• Fresh. Directories without a venv are re-checked on each visit — a venv you create later is picked up immediately.
• Quiet. The hook fires only on actual directory changes, not on every shell prompt.
• Polite. Activate a venv by hand and AutoActivator leaves it alone — no automatic switching until you deactivate.

And it's fast — a cd hook has no business being slow

Wall-clock time for the hook to fire on a single cd into a project with a .venv, cold cache, in an ubuntu:24.04 container. Reproduce with bench/bench.sh.

Install

You need bash or zsh, git, and Linux or macOS — both covered by CI, including macOS's stock bash 3.2. No Python required. (Plot twist: a Python tool that doesn't need Python.)

# zsh only
curl -sSL https://raw.githubusercontent.com/aymenkrifa/autoactivator/main/setup.sh | bash -s zsh

# bash only
curl -sSL https://raw.githubusercontent.com/aymenkrifa/autoactivator/main/setup.sh | bash -s bash

# both
curl -sSL https://raw.githubusercontent.com/aymenkrifa/autoactivator/main/setup.sh | bash -s zsh bash

Then restart your terminal, or source ~/.zshrc / source ~/.bashrc. Later on:

# pull the latest version and re-source the hook in your current shell
autoactivator update

# remove the hook from your rc files (backs them up first);
# add --purge to also delete ~/.autoactivator
autoactivator uninstall

Prefer to see what you're running first? Manual installation is three lines: clone, chmod, run.

Tool support

The rule of thumb: if the venv directory lives anywhere inside your project, AutoActivator will find it. External venv layouts are out of scope for now.

Multiple venvs in one project

First match wins, in this order: $AUTOACTIVATOR_VENV_NAME → .venv → venv → env → virtualenv → first venv-looking directory (alphabetical).

Prefer a non-standard name?

# add before the AutoActivator block in your shell config
export AUTOACTIVATOR_VENV_NAME=myenv

If the named directory doesn't exist in a project, the standard priority list applies — the override is a preference, not a hard requirement.

Security note

Activating a venv means source-ing its bin/activate — so cd-ing into an untrusted checkout executes whatever shell code its venv-shaped directories contain. If you routinely clone code you don't trust, inspect it before cd-ing in. (Tools like direnv address this with a per-directory allow-list; AutoActivator deliberately stays zero-config.)