How `uv run` Works, Including `flet build` and `flet run`

The hardest part of uv run is not the word run. It is knowing where uv stops interpreting your command and where your actual command begins.

What `uv run` does

The notes describe uv run simply: it runs a command or script.

uv run python app.py

That description is small, but the behavior is richer than it first looks. uv is acting as the front door. The command after run is the thing being executed.

What happens to the command

The notes say that when you pass a command after uv run, uv ensures that the command runs in a Python environment.

That is the key idea. uv is not only launching a command. It is shaping the context that command runs inside.

The notes also add an important detail: if no suitable project environment exists, uv creates one and updates it before invoking the command. If a virtual environment already exists, the command runs within it.

uv run is really about execution plus environment handling, not execution alone.

The syntax constraint that matters most

The most important constraint in the notes is this: all options to uv must be provided before the command and its options.

That tells you there is a boundary line in the command.

uv run python app.py

In that example, uv run is the part uv interprets directly. After that, python app.py belongs to the command being run.

The notes make this even more explicit: arguments after the command are not interpreted as arguments to uv.

Why that boundary matters

Beginners often expect one command line to have one interpreter. But uv run is really a handoff. First uv interprets its own part. Then it hands the rest to the command you asked it to run.

Once you see that, the syntax becomes less mysterious. You stop wondering why an option is not doing what you expected, because you start asking a better question: “Whose option is this?”

Running `flet` through `uv run`

The notes include a concrete example with flet.

uv run flet run

Here, uv is ensuring Python-environment-aware execution, and the actual command being run is flet run.

The notes also include:

uv run flet build macos

In that version, the command being run is flet build, and the notes add a constraint: you must specify a target platform.

The listed target platforms are:

macos, linux, windows, web, apk, aab, ipa, and ios-simulator.

A readable way to parse these commands

Try reading from left to right in three chunks:

Chunk one: uv run — use uv to execute something in a Python-aware environment.

Chunk two: flet — this is the command being invoked.

Chunk three: build macos or run — these are arguments for flet, not for uv.

What to remember

uv run is a boundary-setting command. It prepares execution inside a Python environment, then passes control to the command you named. The most important habit is learning where uv options stop and where the invoked command’s options begin.

Raell Dottin's Technical Blog