mirror of
https://github.com/astral-sh/uv.git
synced 2025-07-10 06:45:00 +00:00

Some checks are pending
CI / cargo dev generate-all (push) Blocked by required conditions
CI / cargo shear (push) Waiting to run
CI / Determine changes (push) Waiting to run
CI / lint (push) Waiting to run
CI / cargo clippy | ubuntu (push) Blocked by required conditions
CI / cargo clippy | windows (push) Blocked by required conditions
CI / cargo test | ubuntu (push) Blocked by required conditions
CI / cargo test | macos (push) Blocked by required conditions
CI / cargo test | windows (push) Blocked by required conditions
CI / check windows trampoline | aarch64 (push) Blocked by required conditions
CI / check windows trampoline | i686 (push) Blocked by required conditions
CI / check windows trampoline | x86_64 (push) Blocked by required conditions
CI / test windows trampoline | i686 (push) Blocked by required conditions
CI / test windows trampoline | x86_64 (push) Blocked by required conditions
CI / typos (push) Waiting to run
CI / mkdocs (push) Waiting to run
CI / build binary | windows aarch64 (push) Blocked by required conditions
CI / build binary | linux libc (push) Blocked by required conditions
CI / build binary | linux musl (push) Blocked by required conditions
CI / build binary | macos aarch64 (push) Blocked by required conditions
CI / build binary | macos x86_64 (push) Blocked by required conditions
CI / build binary | windows x86_64 (push) Blocked by required conditions
CI / cargo build (msrv) (push) Blocked by required conditions
CI / build binary | freebsd (push) Blocked by required conditions
CI / ecosystem test | pydantic/pydantic-core (push) Blocked by required conditions
CI / ecosystem test | prefecthq/prefect (push) Blocked by required conditions
CI / ecosystem test | pallets/flask (push) Blocked by required conditions
CI / smoke test | linux (push) Blocked by required conditions
CI / check system | alpine (push) Blocked by required conditions
CI / smoke test | macos (push) Blocked by required conditions
CI / smoke test | windows x86_64 (push) Blocked by required conditions
CI / smoke test | windows aarch64 (push) Blocked by required conditions
CI / integration test | conda on ubuntu (push) Blocked by required conditions
CI / integration test | deadsnakes python3.9 on ubuntu (push) Blocked by required conditions
CI / integration test | free-threaded on windows (push) Blocked by required conditions
CI / integration test | pypy on ubuntu (push) Blocked by required conditions
CI / integration test | pypy on windows (push) Blocked by required conditions
CI / integration test | graalpy on ubuntu (push) Blocked by required conditions
CI / integration test | graalpy on windows (push) Blocked by required conditions
CI / integration test | pyodide on ubuntu (push) Blocked by required conditions
CI / integration test | github actions (push) Blocked by required conditions
CI / integration test | free-threaded python on github actions (push) Blocked by required conditions
CI / integration test | determine publish changes (push) Blocked by required conditions
CI / integration test | uv publish (push) Blocked by required conditions
CI / integration test | uv_build (push) Blocked by required conditions
CI / check cache | ubuntu (push) Blocked by required conditions
CI / check cache | macos aarch64 (push) Blocked by required conditions
CI / check system | python on debian (push) Blocked by required conditions
CI / check system | python on fedora (push) Blocked by required conditions
CI / check system | python on ubuntu (push) Blocked by required conditions
CI / check system | python on rocky linux 8 (push) Blocked by required conditions
CI / check system | python on rocky linux 9 (push) Blocked by required conditions
CI / check system | graalpy on ubuntu (push) Blocked by required conditions
CI / check system | pypy on ubuntu (push) Blocked by required conditions
CI / check system | pyston (push) Blocked by required conditions
CI / check system | python on macos aarch64 (push) Blocked by required conditions
CI / check system | homebrew python on macos aarch64 (push) Blocked by required conditions
CI / check system | python on macos x86-64 (push) Blocked by required conditions
CI / check system | python3.10 on windows x86-64 (push) Blocked by required conditions
CI / check system | python3.10 on windows x86 (push) Blocked by required conditions
CI / check system | python3.13 on windows x86-64 (push) Blocked by required conditions
CI / check system | x86-64 python3.13 on windows aarch64 (push) Blocked by required conditions
CI / check system | windows registry (push) Blocked by required conditions
CI / check system | python3.12 via chocolatey (push) Blocked by required conditions
CI / check system | python3.9 via pyenv (push) Blocked by required conditions
CI / check system | python3.13 (push) Blocked by required conditions
CI / check system | conda3.11 on macos aarch64 (push) Blocked by required conditions
CI / check system | conda3.8 on macos aarch64 (push) Blocked by required conditions
CI / check system | conda3.11 on linux x86-64 (push) Blocked by required conditions
CI / check system | conda3.8 on linux x86-64 (push) Blocked by required conditions
CI / check system | conda3.11 on windows x86-64 (push) Blocked by required conditions
CI / check system | conda3.8 on windows x86-64 (push) Blocked by required conditions
CI / check system | amazonlinux (push) Blocked by required conditions
CI / check system | embedded python3.10 on windows x86-64 (push) Blocked by required conditions
CI / benchmarks | walltime aarch64 linux (push) Blocked by required conditions
CI / benchmarks | instrumented (push) Blocked by required conditions
Addressing the comment at https://github.com/astral-sh/uv/issues/12108#issuecomment-2925703719
99 lines
3.3 KiB
Markdown
99 lines
3.3 KiB
Markdown
# Running commands in projects
|
|
|
|
When working on a project, it is installed into the virtual environment at `.venv`. This environment
|
|
is isolated from the current shell by default, so invocations that require the project, e.g.,
|
|
`python -c "import example"`, will fail. Instead, use `uv run` to run commands in the project
|
|
environment:
|
|
|
|
```console
|
|
$ uv run python -c "import example"
|
|
```
|
|
|
|
When using `run`, uv will ensure that the project environment is up-to-date before running the given
|
|
command.
|
|
|
|
The given command can be provided by the project environment or exist outside of it, e.g.:
|
|
|
|
```console
|
|
$ # Presuming the project provides `example-cli`
|
|
$ uv run example-cli foo
|
|
|
|
$ # Running a `bash` script that requires the project to be available
|
|
$ uv run bash scripts/foo.sh
|
|
```
|
|
|
|
## Requesting additional dependencies
|
|
|
|
Additional dependencies or different versions of dependencies can be requested per invocation.
|
|
|
|
The `--with` option is used to include a dependency for the invocation, e.g., to request a different
|
|
version of `httpx`:
|
|
|
|
```console
|
|
$ uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"
|
|
0.26.0
|
|
$ uv run --with httpx==0.25.0 python -c "import httpx; print(httpx.__version__)"
|
|
0.25.0
|
|
```
|
|
|
|
The requested version will be respected regardless of the project's requirements. For example, even
|
|
if the project requires `httpx==0.24.0`, the output above would be the same.
|
|
|
|
## Running scripts
|
|
|
|
Scripts that declare inline metadata are automatically executed in environments isolated from the
|
|
project. See the [scripts guide](../../guides/scripts.md#declaring-script-dependencies) for more
|
|
details.
|
|
|
|
For example, given a script:
|
|
|
|
```python title="example.py"
|
|
# /// script
|
|
# dependencies = [
|
|
# "httpx",
|
|
# ]
|
|
# ///
|
|
|
|
import httpx
|
|
|
|
resp = httpx.get("https://peps.python.org/api/peps.json")
|
|
data = resp.json()
|
|
print([(k, v["title"]) for k, v in data.items()][:10])
|
|
```
|
|
|
|
The invocation `uv run example.py` would run _isolated_ from the project with only the given
|
|
dependencies listed.
|
|
|
|
## Legacy Windows Scripts
|
|
|
|
Support is provided for
|
|
[legacy setuptools scripts](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#scripts).
|
|
These types of scripts are additional files installed by setuptools in `.venv\Scripts`.
|
|
|
|
Currently only legacy scripts with the `.ps1`, `.cmd`, and `.bat` extensions are supported.
|
|
|
|
For example, below is an example running a Command Prompt script.
|
|
|
|
```console
|
|
$ uv run --with nuitka==2.6.7 -- nuitka.cmd --version
|
|
```
|
|
|
|
In addition, you don't need to specify the extension. `uv` will automatically look for files ending
|
|
in `.ps1`, `.cmd`, and `.bat` in that order of execution on your behalf.
|
|
|
|
```console
|
|
$ uv run --with nuitka==2.6.7 -- nuitka --version
|
|
```
|
|
|
|
## Signal handling
|
|
|
|
uv does not cede control of the process to the spawned command in order to provide better error
|
|
messages on failure. Consequently, uv is responsible for forwarding some signals to the child
|
|
process the requested command runs in.
|
|
|
|
On Unix systems, uv will forward SIGINT and SIGTERM to the child process. Since terminals send
|
|
SIGINT to the foreground process group on Ctrl-C, uv will only forward a SIGINT to the child process
|
|
if it is sent more than once or the child process group differs from uv's.
|
|
|
|
On Windows, these concepts do not apply and uv ignores Ctrl-C events, deferring handling to the
|
|
child process so it can exit cleanly.
|