Ship your own command-line app that anyone installs with one line

To make something other people can install with one command, Python needs a package: your code in a folder, plus a pyproject.toml file that says its name, its version, what it depends on, and which command it creates. uv ↗ makes that skeleton for you, then builds, tests and installs it.

Check you have uv and which version:

uv --version

You want 0.12 or newer. To update: uv self update if you used uv's own installer, winget upgrade --id astral-sh.uv -e if you used winget, brew upgrade uv on a Mac with Homebrew. No uv at all? Install it, then close the terminal and open a new one:

winget install --id=astral-sh.uv -e

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

Now make the project. The --package flag is the important part: it gives you a src folder, a build system and a command-line entry point, all the things a plain script project doesn't have.

cd $HOME\Documents
uv init --package tidyup
cd tidyup

cd ~/Documents
uv init --package tidyup
cd tidyup

Initialized project `tidyup` at `...\tidyup`

You get this layout. uv also made the folder a Git repository, with a .gitignore that keeps the .venv folder and build files out of it:

tidyup/
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
└── src/
    └── tidyup/
        └── __init__.py

Open pyproject.toml in your editor. This is what uv wrote:

[project]
name = "tidyup"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

[project.scripts]
tidyup = "tidyup:main"

[build-system]
requires = ["uv_build>=0.12.24,<0.13.0"]
build-backend = "uv_build"

• [project.scripts] is the entry point. The left side is the command people will type: tidyup. The right side says where Python finds the code to run: the main function in the tidyup package. When the package is installed, a small launcher called tidyup (tidyup.exe on Windows) is made that runs it.
• [build-system] names the tool that turns your folder into an installable file. uv uses its own, uv_build. The upper limit (<0.13.0) stops a future uv release from quietly changing how your package builds.
• requires-python comes from the Python uv found on your PC. Yours may say a different version. Anything from 3.10 up works with this mission.

Change the description to something real, like "Tidy a messy folder (like Downloads) into subfolders by file type.". It shows on PyPI if you publish. Then run the command uv already wired up:

uv run tidyup

Using CPython 3.12.13
Creating virtual environment at: .venv
   Building tidyup @ file:///.../tidyup
      Built tidyup @ file:///.../tidyup
Installed 1 package in 31ms
Hello from tidyup!

uv run made a private environment (.venv) inside the project, installed your package into it, and ran the tidyup command from there. Nothing has been installed for the rest of your PC yet. That comes in step 5.