uv Python Virtual Environment Usage

uv is a fast Python package manager that creates isolated virtual environments in .venv/ by default. Scripts run directly with python won’t find packages installed via uv unless the venv is activated or uv run is used.

Why / When to Use

When you install packages with uv pip install and then run a script — especially from a cron job or a different shell — the system Python is used instead of the venv Python, causing ModuleNotFoundError.

Core Concept / Commands

Run a script using the uv venv

uv run python script.py

This is the safest approach — no manual activation needed, works reliably from cron.

Activate the venv manually

source .venv/bin/activate
python script.py

Install a package into the project venv

uv pip install requests

Check which Python is active

which python
# Should show .venv/bin/python if venv is active

Key Options / Variants

Cron job with uv run

0 * * * * cd /path/to/project && uv run python script.py

Always cd to the project directory first so uv finds the .venv folder.

Using uv with pip-style requirements

uv pip install -r requirements.txt

Gotchas

• uv pip install installs into .venv/ in the current directory — running the script from a different directory means a different .venv (or none).
• Cron jobs that ran as root previously may have created state files owned by root that your user script can’t write. Fix: sudo rm /tmp/<state-file>.
• If you see “No module named X” after installing, check which python — you’re likely using the system Python.

Source

Conversation “Zsh home button not working” and “Cron job scheduling issue” — 2026-05-15