🍨 scoop

⚠️ Work in Progress — Under active development. API may change.

One scoop, endless envs — pyenv-style Python environment manager powered by uv

What is scoop?

scoop scoops up uv's blazing speed — centralizing all your Python virtual environments in one place.

🍨 Like an ice cream parlor — all flavors (envs) in one freezer (~/.scoop/), served instantly with a single scoop.

Problem	scoop Solution
`.venv` scattered across projects	`~/.scoop/virtualenvs/` centralized
Manual `source .venv/bin/activate`	Auto-activate on directory entry
pyenv-virtualenv is slow	uv-powered, 100x+ faster

Installation

Prerequisites

Dependency	Install	Why
uv	`curl -LsSf https://astral.sh/uv/install.sh \| sh`	Python installation backend
Rust	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh`	Build from source

Install scoop

cargo install scoop-uv

Cargo installs binaries to ~/.cargo/bin. Ensure it's in your PATH:

# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.cargo/bin:$PATH"

Or restart your terminal after installing Rust.

Shell Setup

Step 1: Add to your shell config

Zsh (macOS default):

echo 'eval "$(scoop init zsh)"' >> ~/.zshrc
source ~/.zshrc

Bash:

echo 'eval "$(scoop init bash)"' >> ~/.bashrc
source ~/.bashrc

Step 2: Verify

scoop --version
# → scoop 0.x.x 🍨

What this enables

✅ Auto-activation — enter a directory with .scoop-version, environment activates
✅ Tab completion — commands, environments, Python versions
✅ Shell wrapper — scoop activate/deactivate works correctly

Using with pyenv

Add scoop after pyenv in your rc file:

# ~/.zshrc (order matters!)
eval "$(pyenv init -)"       # 1. pyenv first
eval "$(scoop init zsh)"     # 2. scoop second

Options

Variable	Effect
`SCOOP_NO_AUTO=1`	Disable auto-activation
`SCOOP_HOME=/path`	Custom scoop directory (default: `~/.scoop`)

# Example: disable auto-activation
echo 'export SCOOP_NO_AUTO=1' >> ~/.zshrc

Quick Start

# Install Python
scoop install 3.12

# Create a virtual environment
scoop create myproject 3.12

# Set for current directory (auto-activates)
scoop use myproject
(myproject) $ pip install requests

# Manage environments
scoop list                 # List all environments
scoop remove myproject     # Delete environment

Commands

Command	Description
`scoop create <name> [version]`	Create virtual environment
`scoop use <name>`	Set local environment (auto-activates)
`scoop use <name> --link`	Also create `.venv` symlink for IDE
`scoop use <name> --global`	Set global default
`scoop list`	List environments
`scoop list --pythons`	List installed Python versions
`scoop remove <name>`	Delete environment
`scoop install [version]`	Install Python (default: latest)
`scoop install --stable`	Install oldest supported Python
`scoop uninstall <version>`	Remove Python version

For complete command reference, see docs/commands.md.

Documentation

Command Reference - Complete command documentation
Development Guide - Contributing and development setup

License

Licensed under either of:

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work shall be dual licensed as above, without any additional terms or conditions.

Support

If you find this project useful, consider buying me a coffee!

Acknowledgments

This project stands on the shoulders of giants:

uv by Astral — The blazing-fast Python package manager that powers scoop's backend. Without uv's incredible speed and reliability, scoop wouldn't exist. Thank you to Charlie Marsh and the entire Astral team for revolutionizing Python tooling.
pyenv — The original inspiration for scoop's workflow. pyenv taught us how environment management should feel.

scoop-uv 0.2.6