Quick Start

This guide walks you through the basic scuv workflow.

1. Set Up Shell Integration

Zsh (macOS default):

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

Bash:

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

Fish:

echo 'scuv init fish | source' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

PowerShell:

Add-Content -Path $PROFILE -Value 'Invoke-Expression (& scuv init powershell)'
. $PROFILE

2. Install Python

# Install latest Python
scuv install 3.12

# Verify installation
scuv list --pythons

3. Create a Virtual Environment

scuv create myproject 3.12

This creates a virtual environment at ~/.scuv/virtualenvs/myproject/.

If Python 3.12 isn’t installed yet, add --install-python to install it on demand:

scuv create myproject 3.12 --install-python

4. Use the Environment

cd ~/projects/myproject
scuv use myproject

This:

1. Creates .scuv-version file in the current directory
2. Activates the environment (prompt shows (myproject))

5. Work With Your Environment

(myproject) $ pip install -r requirements.txt

# If the file is in a different location:
(myproject) $ pip install -r path/to/requirements.txt

# Verify installed packages
(myproject) $ pip list

6. Auto-Activation

Once configured, entering a directory with .scuv-version automatically activates the environment:

cd ~/projects/myproject
# (myproject) appears in prompt automatically

Common Commands

IDE Integration

Create a .venv symlink for IDE compatibility:

scuv use myproject --link

This creates .venv pointing to the scuv environment, recognized by VS Code, PyCharm, etc.

Next Steps

• See Shell Integration for advanced configuration
• See Commands for full command reference