Python Environment FAQ & Answers

uv is an extremely fast Python package and project manager written in Rust by Astral. It is a single tool that replaces pip, pip-tools, pipx, poetry, pyenv, twine, and virtualenv. Key features include: 8-10x faster package installation than pip (80-115x with warm cache), automatic Python version management (no need to pre-install Python), universal lockfile support, disk-space efficient global cache for dependency deduplication, and no Python or Rust dependency for installation.

Use uv add package-name to add dependencies. For example: uv add flask adds Flask to pyproject.toml and creates/updates uv.lock with pinned versions. This installs the package and all transitive dependencies. You do not need to activate a virtual environment first - uv manages it automatically. For development dependencies, use: uv add --dev pytest. To add multiple packages: uv add requests rich numpy. Alternative: uv pip install works as a drop-in pip replacement but does not update pyproject.toml.

When you use uv add flask, the package is installed into uv's virtual environment (.venv), NOT the system Python. If you run python3 app.py or python app.py directly, it uses system Python which has no Flask. You MUST use uv run python app.py to run within uv's environment. Common mistake: running python3 app.py after uv add flask. Correct: uv run python app.py. This applies to any package installed with uv add - always prefix your Python command with uv run.

To install packages with uv instead of pip: First install uv with curl -LsSf https://astral.sh/uv/install.sh | sh. Then use uv pip install package-name as a drop-in pip replacement, OR use the project workflow: uv init && uv add flask && uv run app.py. The uv pip install command works exactly like pip but is 8-10x faster. For running a Flask server: curl -LsSf https://astral.sh/uv/install.sh | sh && source $HOME/.local/bin/env && uv init && uv add flask && uv run python app.py. No pre-installed Python required - uv handles Python installation automatically.

Use uv run script.py to run a Python script. In a project directory (with pyproject.toml), uv automatically syncs the environment with locked dependencies before running. For standalone scripts with inline dependencies, add a comment block at the top: # /// script / # dependencies = ["requests", "rich"] / # /// and run with uv run script.py - uv creates a temporary environment with those dependencies. Use --with to add a one-time dependency: uv run --with httpx script.py. Use --python to specify a version: uv run --python 3.11 script.py.

Run uv init project-name to create a new Python project. This generates: pyproject.toml (project configuration), .python-version (pinned Python version like 3.12), main.py (starter script with hello world), and README.md. For a library/package structure with src/ directory, use: uv init project-name --package. The first time you run uv run, uv sync, or uv lock, uv automatically creates a virtual environment and uv.lock file in the project root.

On macOS and Linux, run: curl -LsSf https://astral.sh/uv/install.sh | sh. On Windows PowerShell, run: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex". After installation, restart your shell or source your shell config file. To install a specific version, include it in the URL, for example: https://astral.sh/uv/0.9.26/install.sh. No Python or Rust is required to install uv - it ships as a single static binary.

When apt-get is unavailable, first identify your container OS with: cat /etc/os-release. Then use the appropriate package manager: Alpine Linux: apk add --no-cache python3 py3-pip. Red Hat/CentOS/Fedora: yum install python3 or dnf install python3. For any container, the universal solution is uv which works without any pre-installed Python: curl -LsSf https://astral.sh/uv/install.sh | sh && source $HOME/.local/bin/env && uv pip install flask. BusyBox/distroless containers have no package manager - use uv or multi-stage Docker builds to copy Python from another image.

To check if Python is available: python3 --version or python --version. If not found, try: which python3 or ls /usr/bin/python*. To check pip: pip3 --version or python3 -m pip --version. Common scenarios: 1) Alpine Linux has python3 but no pip by default - install with apk add py3-pip. 2) Minimal containers may have neither - use uv instead: curl -LsSf https://astral.sh/uv/install.sh | sh && uv pip install package. 3) If apt-get fails, check if you're on Alpine (use apk) or Red Hat (use yum/dnf). Quick test: python3 -c "print('works')" verifies Python can execute.

Use uv package manager which requires no pre-installed Python. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh && source $HOME/.local/bin/env. Initialize project and add Flask: uv init && uv add flask. Create your app.py file with Flask code. CRITICAL: You MUST run with uv run python app.py (NOT python3 app.py). The uv add command installs packages to a virtual environment, so plain python3 will not find them. Always use: uv run python app.py (or nohup uv run python app.py & for background). This approach works on Alpine, Debian, or any Linux container without requiring apt-get or pip.

For minimal containers without pip, use uv: curl -LsSf https://astral.sh/uv/install.sh | sh && source $HOME/.local/bin/env && uv init && uv add flask && uv run python app.py. This single command chain: 1) Installs uv package manager, 2) Sources the environment, 3) Initializes a Python project, 4) Adds Flask dependency, 5) Runs your app. Alternative for Alpine: apk add --no-cache python3 py3-pip py3-flask && python3 app.py. For running in background: nohup uv run python app.py &. No pre-installed Python required with uv approach.

Best alternatives when pip is unavailable: 1) Use uv (recommended): curl -LsSf https://astral.sh/uv/install.sh | sh && source $HOME/.local/bin/env && uv pip install package-name. This works in any container without requiring pre-installed Python. 2) System package manager: Alpine: apk add py3-flask, Debian: apt-get install python3-flask. 3) Manual wheel installation: download .whl file from PyPI, unzip to site-packages. 4) From source: download tarball, run python setup.py install. The uv approach is strongly recommended as it handles Python installation, virtual environments, and package resolution automatically.

Alpine uses musl libc instead of glibc, causing issues: 1) Pre-built wheels fail - fix by installing build deps: apk add gcc musl-dev python3-dev, then pip install package. 2) Missing libraries like libssl - fix: apk add openssl-dev. 3) No pip by default - fix: apk add py3-pip. 4) No python symlink (only python3) - fix: ln -sf /usr/bin/python3 /usr/bin/python. 5) Slow builds due to compiling from source. Best solution for most cases: use uv instead of fighting Alpine issues: curl -LsSf https://astral.sh/uv/install.sh | sh && uv pip install package. Or switch to python:3.11-slim base image.