Let's check it out!
History
Python Setup Cheat Sheet detailed how to install pip as the de facto standard package-management system on Windows, Mac OS/X and Linux. However, requirements.txt does not lock down transitive dependencies + versioning which becomes brittle. Poetry solved this problem using pyproject.toml configuration and lock file.
uv
Replicating Poetry with more deterministic builds using using pyproject.toml configuration and lock file, uv is built in Rust by Astral as a full rethinking of Python packaging designed for speed and simplicity. uv: pitched as "A single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv and more". Here is a detailed article comparing the Python Packaging Landscape: Pip vs. Poetry vs. UV from a developer's standpoint.
IMPORTANT
First check out the traditional way using python and pip to compare and illustrate benefits of now using uv:
Virtual Environment
A virtual environment isolates Python project interpreter and installed packages from the system and other Python projects which means each project should have its own environment, its version and dependencies.
Create a virtual environment in the traditional way using python and pip then activate virtual environment:
|
python -m venv .venv | |
| Linux OR Mac OS/X | source .venv/bin/activate |
| Windows | .\.venv\Scripts\activate |
Next, install packages using python, pip and requirements.txt OR poetry with pyproject.toml configuration:
Brittle and/or slow [transitive] dependency resolution!
Installation
Download and install uv for Linux, Mac OS/X or Windows OR Launch PyCharm and install from home page:
| Linux | curl -LsSf https://astral.sh/uv/install.sh | sh |
| Mac OS/X | brew update && brew install uv |
| Windows | powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" |
uv init
Create new directory and execute following commands to initialize Python project with an interpreter version
Launch Terminal | Execute the following commands:
mkdir HelloUV cd HelloUV uv init --python 3.11.11 |
uv venv
Navigate into Python project and execute following commands to create the virtual environment and activate
Launch Terminal | Execute the following commands:
uv venv --python 3.11.11 source .venv/bin/activate # Windows: .\.venv\Scripts\activate |
uv python
At this point you have Python project initialized with virtual environment activated. Confirm correct version of Python interpreter installed and activate. When using PyCharm ensure the IDE interpreter path is aligned!
Inside PyCharm Terminal | Execute the following commands:
which python `which python` --version |
uv add
Install Python packages either using uv pip install or uv add commands. Prefer uv add because this updates pyproject.toml file automagically thus you are able to execute uv sync command to install the dependencies.
Inside PyCharm Terminal | Execute the following commands:
uv pip list uv add requests uv sync |
uv tree
After execute uv add you can verify what is installed by checking pyproject.toml file or execute uv pip list but another useful method is uv tree which shows hierarchy of all your project's dependencies and relationships.
Inside PyCharm Terminal | Execute the following command: uv tree
uv sync
Execute uv add or update pyproject.toml to install dependencies. Execute uv sync to update environment.
uv lock
The uv.lock file records all the exact versions of all project dependencies UV figures are compatible from the pyproject.toml file to ensure constant deterministic builds with the same dependenices each time and CI/CD
uv tool
UV tool installs persistent tools into virtual environment that are required for that particular Python project:
Inside PyCharm Terminal | Execute the following commands:
uv tool list uv tool install ruff uv tool run ruff check uv tool upgrade --all uv tool uninstall ruff uv tool list |
uvx tool
Finally uvx is an alias for uv tool run but is designed to be run immediately without installing it persistently:
Inside PyCharm Terminal | Execute the following command: uvx ruff check
uv cache
When you use uv all tools and dependencies are stored in cache. These commands remove all cached data:
uv cache clean rm -r "$(uv python dir)" rm -r "$(uv tool dir)" |
Commands
Here is a quick summary of popular uv commands used during workflow. A comprehensive list can be found.
uv init --app # Scaffold project uv python install 3.11 # Install Python uv venv --python 3.11 # Create virtual environment uv add requests # Add dependencies uv add -D pytest # Add dev dependencies uv sync --frozen # Sync (locked) uv sync # Sync (normal) uv run python main.py # Run program uv run python -V # Show Python uvx ruff check . # Run tools ad‑hoc uv lock # Update lockfile |
Docker
A well-built uv Docker image simplifies deployment + ensures application runs consistently in environment:
FROM python:3.11.11-slim
# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
COPY . /app
WORKDIR /app
# Install dependencies and clear cache
RUN uv sync --no-dev --frozen
RUN rm -rf ~/.cache/uv
CMD ["python", "-c", "print('Hello, World!')"]
|
This is an example Dockerfile snippet how to integrate uv! But build and run execution with the commands:
docker build -t uv-hello . docker run --rm uv-hello |
GitHub Actions
A common GitHub Actions pattern is to use UV to install only Prod dependencies during your build or deploy:
name: Testing on: push: branches: - "main" jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install UV run: curl -LsSf https://astral.sh/uv/install.sh | sh - name: Sync only prod dependencies run: uv sync --no-group dev --group prod - name: Run tests run: uv run pytest |
Summary
To summarize, uv has been pitched "One Tool for Everything" as uv replaces pip, virtualenv, pip-tools, pipx, poetry, pyenv, twine and is fast at every step. However, this has only scratched the surface as uv integrates well with other tools for fast reproducible Python workflows such as direnv, pre-commit hooks, pdm + more!
| uv | Handles Python installs, environment creation, and dependency resolution with locking |
| direnv | Evaluates .envrc managing environment variables automatically applied to shell session |
| pdm | Orchestrate workflows + provide unified tooling to build, version, and publish pacakges |
