Python

Installation

Our recommendation is to use uv to install and manage Python versions, packages, and virtual environments.

Install uv

Use the standalone uv installer to install uv for you OS.

Install Python

uv installs and manages Python interpreters itself — there is no need for pyenv, Homebrew, or the system Python.

uv python install 3.14      # install a specific version
uv python list              # show installed and available versions
uv python upgrade           # upgrade managed versions

Installs are user-level and never require sudo. Interpreters are stored in ~/.local/share/uv/python/, with versioned executables (e.g. python3.14) placed on PATH in ~/.local/bin/. Your system Python is left untouched.

Create a new project using uv

uv is a highly performant and comprehensive tool that can install and manage:

• Python itself
• packages / dependencies
• virtual environments / projects

uv init .
# or if you want to create a library project
uv init --lib .
# or local package
uv init --package .

Add dependencies

For example, to add polars and duckdb as dependencies, you can use the following command:

uv add polars duckdb

This will create the pyproject.toml file and add the dependencies to it, as well as create a virtual environment for the project. You can also add other dependencies as needed.

Development dependencies

Development dependencies are packages that are only needed during development, such as testing frameworks or linters. To add development dependencies, you can use the --dev flag. For example, to add pytest as a development dependency, you can use the following command:

uv add --dev pytest

This will add the specified packages to the dev dependency group of the pyproject.toml file.

uv add --dev ipykernel

Working without a project

Not everything needs a pyproject.toml. For a quick console session, a standalone script, or a command-line tool, uv can build a throwaway environment on demand.

Packages resolved this way are stored in the global cache (~/.cache/uv) and the environment is hardlinked from it, so nothing is duplicated on disk and nothing accumulates in your working directory. The first invocation resolves and downloads; subsequent ones are near-instant.

Self-contained scripts

A script can declare its own dependencies inline using PEP 723 metadata, making it runnable anywhere uv is installed — no project, no virtual environment, no requirements.txt:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["polars", "httpx"]
# ///

import polars as pl

Make it executable with chmod +x analysis.py and run it directly.

Useful related commands:

uv add --script analysis.py polars   # add a dependency to the inline block
uv lock --script analysis.py         # pin versions in analysis.py.lock

Use inline metadata for scripts that travel alone. If a script imports your own modules, or several scripts share a dependency set worth locking together, use a project with a pyproject.toml instead.

Pruning the uv cache

uv caches downloaded packages and Python versions to speed up future installations. This needs to be pruned from time to time to free up disk space:

uv cache prune

Resources

uv docs