sitdraw

How to install and use uv: init a project, add a package, run a script

Install uv from the official steps, create a project, add one package, and run a script with uv run.

To manage a Python project with uv on your machine, finish four jobs: install from the official channel, uv init, uv add one package, then uv run a script.

Follow docs.astral.sh/uv/ instead of guessing package names. The queries are how to install uv, uv init, and run a script with uv run. The installer lives at astral.sh/uv.

uvAstral command name
initWrites pyproject.toml
runExecutes in the project env

Install the official binary for your OS

macOS and Linux

Official script: curl -LsSf https://astral.sh/uv/install.sh | sh. Or brew install uv. Open a new terminal and run uv --version.

Windows

PowerShell: irm https://astral.sh/uv/install.ps1 | iex. Start a new session and confirm uv is on PATH.

StepCommandWatch for
Installuv --versionThe current shell must see the official binary
Projectuv init myprojectpyproject.toml should appear
Dependencyuv add httpxUse the PyPI name; the lockfile updates
Scriptuv run python hello.pyUses the project env; no manual activate

Install, init, add a package, run a script

  1. 01
    Install and confirm the version

    Follow docs.astral.sh/uv/getting-started/installation/ for the script or Homebrew. uv --version should print a version. If the command is missing, open a new terminal and check PATH.

  2. 02
    Create a project

    In the parent directory run uv init myproject, then cd myproject. You should see pyproject.toml. An empty folder can take a bare uv init.

  3. 03
    Add one package

    Run uv add httpx as an example. uv resolves deps, writes the lockfile, and prepares the environment. On failure, check the package name and the network; do not hand-edit a half-written lockfile.

  4. 04
    Write and run a script

    Create hello.py that uses the new package, then uv run python hello.py. To pin an interpreter first, run uv python install.

curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version
uv init myproject
cd myproject
uv add httpx
# After you write hello.py:
uv run python hello.py
Is the official install script required?
No. The docs also list Homebrew, WinGet, and other channels. Pick one and verify with uv --version. Do not stack several copies that fight over PATH.
Do I still create a venv myself?
Not for daily use. uv add and uv run use the project environment. Add .venv to .gitignore; do not commit it.
How is uv run different from python?
A system python may not see project dependencies. uv run selects the project interpreter and installed packages.
Does install replace a shared diagram?
No. This is a Python toolchain. When the meeting is the same diagram, open sitdraw.

Get uv on PATH first

Until uv --version works, do not treat a failed init as a template bug. Most failures are a shell that never loaded the PATH the installer changed.

Start the picture