uv run -m misses inline script requirements: choose module or script mode

By ON Lab · Sources checked November 8, 2026

When a Python file contains inline script metadata, running its path and running its module name are different launch modes. If a dependency or Python requirement appears to be ignored after switching to uv run -m, compare the exact commands before editing your environment. Decide whether the code is a standalone managed script or a module using a project environment.

The reader problem behind this check

A linked uv issue reports that a file with inline dependency metadata ran successfully by path, while running the same code with a module name failed to import its dependency. The reporter wanted internal, multi-file scripts rather than a distributable package. A maintainer discussed whether inline metadata was intended for that pattern. The report is useful evidence of a launch-mode mismatch, rather than proof that every missing import is the same bug.

The current command reference defines the module option as the Python module launch mode. The script guide describes inline metadata on a script file, including its own dependencies and Python requirement. These are separate contracts. A Python source file being reachable as a module does not establish that uv will use that file's inline metadata for the module invocation.

Write down the command that actually failed

Invocation	What to inspect	Common mistaken inference
uv run path/to/check.py	Script file and its inline metadata	That the surrounding project's dependencies are always added
uv run -m example.check	Module launch and selected environment	That metadata in the module file was necessarily processed
uv run python path/to/check.py	A Python command receiving a file argument	That this is identical to uv directly managing that script

The third row is a diagnostic distinction, not an instruction to change a working launch command. Preserve the exact invocation used by the editor, shell script, or CI job. Small changes in the command can change which layer handles the source file.

A bounded offline comparison we executed

We tested uv 0.13.7 on macOS arm64 with Python 3.9.6 already installed. We created a disposable example package containing an empty __init__.py and a check.py file. Its inline metadata deliberately required Python 3.99 or newer, an unavailable version in this environment. The script body only printed its Python version and had no third-party imports.

# /// script
# requires-python = ">=3.99"
# dependencies = []
# ///
import sys
print(sys.version.split()[0])

The unrealistic version is a test marker. Do not use it as a real compatibility requirement. It makes the metadata's effect visible without installing a dependency, contacting a package index, or downloading an interpreter.

uv run --no-project --offline --no-python-downloads example/check.py
uv run --no-project --offline --no-python-downloads -m example.check

The file-path command exited 2 because no interpreter satisfied Python >=3.99. The module command exited 0 and printed 3.9.6. In this bounded case the inline Python request affected direct script execution, while the module invocation used the available interpreter without applying that request.

We invoked an existing uv binary by its absolute path because uv was not on this shell's PATH. The first attempt failed to locate the executable and did not test metadata. The comparison above describes the corrected execution. No uv installation, interpreter download, package download, or authentication was performed.

This experiment verifies a requirement boundary, not the original issue's third-party import failure. It does not test all uv versions, Windows launchers, package entry points, workspace discovery, or the reader's private project. An offline failure can also mean a needed artifact is not cached; it is not automatically evidence of a launch-mode mismatch.

Choose a script when its metadata should travel with the file

The official guide shows uv managing a script's inline dependencies and creating the environment needed to run it. It also states that a script with inline metadata ignores the surrounding project's dependencies, even when run inside that project. Adding a library only to pyproject.toml is therefore not a reliable repair for a standalone script that has its own dependency declaration.

For a script-oriented workflow, put the intended dependencies in the script metadata and use the documented script invocation. The guide's uv add --script command changes that file, so review the diff before using it on shared code. The dependencies field must exist even when its list is empty. Use a real Python requirement matching the script's syntax and supported environments.

When repeatability matters, the guide documents an explicit script lock operation that creates a lockfile adjacent to the script. A project's uv.lock and a script's lockfile have different scopes. Verify which one your launch mode uses rather than assuming an existing lockfile covers every Python file below the same directory.

Choose a project when modules share project dependencies

If the intended command is a module within a multi-file project, define the shared dependencies and Python compatibility in the project's configuration and verify the environment used by that command. Review those changes with the people maintaining the project. Do not copy a dependency declaration into several files simply to silence one missing import.

After an approved configuration update, run the exact original module command and inspect both its exit code and expected output. A command that merely prints a Python version does not prove that the application imports its dependencies, reads its data files, or passes its own tests. Keep those checks separate.

If one launch mode breaks relative imports

Changing from module execution to a file path can alter Python import behavior. Therefore “use the file path” is not a universal solution for a package that relies on relative imports. Record the package layout and the failing import before changing modes. Decide on the intended packaging and environment model instead of alternating flags until one command happens to succeed.

If the failure is about a project Python pin rather than inline metadata, use the interpreter selection check. If a package disappears during project syncing, the exact sync guide addresses a different operation. Neither automatically establishes which inline script metadata was processed.

What to include in a useful bug report

Include the uv version, operating system, minimal file tree, sanitized metadata, exact invocation, exit code, and complete relevant error. Say whether project discovery was enabled, whether an interpreter was already installed, and whether downloads were allowed. Reuse the saved output rather than repeatedly contacting a package index to rediscover the same failure.

A successful repair means the intended command uses the intended declared dependencies and Python compatibility, then completes its real task. Success in a different launch mode is evidence to investigate, not automatic proof that the original workflow is repaired.

Checked November 8, 2026. The no-download comparison was executed locally. The source issue's third-party dependency example, actual project integration, and other platforms were not reproduced.