Skip to main content

uv for Python Projects

Updated Jul 11, 2026 ·

Overview​

uv is a Python package and project manager.

You can use it to create Python projects, install dependencies, run scripts, and manage a project .venv without manually wiring everything together.

Install uv​

For macOS, Linux, and WSL:

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

If curl is not available:

wget -qO- https://astral.sh/uv/install.sh | sh

For Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Another common option on macOS is Homebrew:

brew install uv

Verify the install:

uv --version

Shell Completion​

For Bash, add completion to ~/.bashrc:

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

For Zsh, add completion to ~/.zshrc:

echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

For PowerShell:

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}

Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

Restart the shell after changing the shell profile.

Update uv​

If uv was installed with the standalone installer, update it with:

uv self update

If uv was installed with a package manager, use that package manager instead.

Examples:

brew upgrade uv
winget upgrade --id=astral-sh.uv -e

Create a Project​

Create a new project in the current directory:

uv init
uv sync

Create a new project in a target directory:

uv init my-project
cd my-project
uv sync

uv init creates files such as:

my-project/
|-- .python-version
|-- README.md
|-- main.py
`-- pyproject.toml

Note: uv sync installs dependencies and creates a .venv in the project directory.

Run Python​

Run a Python file through the project environment:

uv run python main.py

For a project created by uv init, this also works:

uv run main.py

Install Dependencies​

Add a dependency to the project:

uv add requests

Add a development dependency:

uv add --dev ipykernel

Sync the environment with the project files:

uv sync

uv sync installs missing dependencies and removes dependencies that are not declared by the project.

Run uv sync inside a project

uv sync expects a pyproject.toml in the current directory or a parent directory.

If there is no project file, use uv pip install <package> instead.

Install into an Existing .venv​

If you are not using a structured uv project, create a virtual environment and install packages directly:

uv venv
uv pip install requests

On macOS, Linux, and WSL, activate it with:

source .venv/bin/activate

On Windows PowerShell, activate it with:

.venv\Scripts\Activate.ps1

Cleanup​

Remove a project virtual environment:

rm -rf .venv
uv sync

For Windows PowerShell:

Remove-Item -Recurse -Force .venv
uv sync

Clean the uv cache:

uv cache clean

Remove installed Python versions and tool environments managed by uv:

rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

For Windows PowerShell:

Remove-Item -Recurse -Force (uv python dir)
Remove-Item -Recurse -Force (uv tool dir)
Check paths before cleanup

Before running recursive cleanup commands, confirm that the path is the project .venv, the uv Python directory, or the uv tool directory.

References​