Introduction

In 2025, many Python projects adopt uv for packaging and script execution. One question on Stack Overflow described a project where the developer tried to call a script defined in pyproject.toml using uv run sacrypt. Despite defining a sacrypt_main function in main.py and declaring [project.scripts] sacrypt = "main:sacrypt_main", running uv run sacrypt resulted in the error “failed to spawn: sacrypt” and a ModuleNotFoundError for sacrypt.

Why the Error Occurs

Missing [build‑system] section

The pyproject.toml file lacked a [build‑system] configuration. uv uses this section to determine how to build and install the package into its environment. Without it, uv cannot import modules properly.

Incorrect script entry

The script was defined as sacrypt = "main:sacrypt_main". In practice, the entry should specify the module path and the function that acts as the CLI entry point (e.g., main:main).

No packaging metadata

Without specifying build dependencies (such as setuptools and wheel), uv cannot compile and install the project, so the executable script does not get created.

Solution

The accepted answer provided a minimal pyproject.toml example that fixes the issue. Here is how to resolve the problem:

Add a [build‑system] section

This tells uv how to build the package. A common configuration uses setuptools:

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

This installs the necessary build backend and ensures your package can be built and installed.

Define the CLI script correctly

In the [project.scripts] section, set the script name to the module path and function that should be executed. If your main.py file contains a main() function that acts as the entry point, define:

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

Make sure main.py is located at the top level of your project and defines a main() function.

Run the script with uv run

After updating pyproject.toml, run:

uv pip install -e .  # optional, to install in editable mode
uv run sacrypt

The script should execute without the “failed to spawn” error.

Optional: use uv init

The uv tool can scaffold a pyproject.toml using uv init, which ensures required sections are present.

Conclusion

The “failed to spawn” error in uv run typically means uv cannot find or build the requested script. Adding a proper [build‑system] section and correctly defining the script entry in [project.scripts] solves the problem. As uv adoption grows in 2025, following this pattern will save you hours of debugging.