How to run a library module?

[ollimandoliini]

What is the recommended way for running a library module like I would do in vanilla python with the -m flag.

E.g.

python -m mylibrary.module

[gusutabopb]

I believe that'd be simply

uv run python -m mylibrary.module

[ollimandoliini]

Thanks! That's what I have been using.

It's a bit confusing because there is no parallel for uv run file.py for running a module.

[charliermarsh]

We could consider adding -m module but in the meantime yes, explicitly adding python there is expected (\cc @zanieb).

[zanieb]

I think we should document this. I'm not sure we should provide a shorthand yet... but it does seem kind of nice?

[johnhoran]

One downside to the uv run python -m mylibrary.module approach is that this doesn't allow for the inline script metadata.

[zanieb]

In that case, your module is defined in a script?

[johnhoran]

Some are in scripts, others are in folders with a __main__.py file.

[rogerbinns]

My package has several command line tools that are invoked via -m. They are not installed as separate commands. For example you can do the following which all take extra parameters.

# gets a database cli shell
python -m apsw
# runs test suite
python -m apsw.tests
# runs benchmark
python -m apsw.speedtest
# runs automatic tracer of SQL
python -m apsw.trace

I have 3 more under development. I was hoping that I could do uvx run apsw, uvx run apsw.speedtest etc perhaps with a -m flag. Sadly that is not the case. Doing uv run python -m apsw.speedtest doesn't automagically install the package like uvx run does.

Please consider adding -m to uvx run or perhaps make that a default fallback behaviour if uvx run doesn't find an installed script.

[gotmax23]

uv run -m makes a lot of sense to me. You're trying to run a module.

[zanieb]

Unless someone can think of another use for the -m flag I think it's fine to use for this and should be an easy first contribution.

cc @konstin

[rogerbinns]

Is the -m flag even necessary? If a relevant binary isn't found by uv run, couldn't it automatically then behave as though -m was provided? I'm most interested in uvx working, so my earlier example would just become uvx apsw ... or uvx apsw.speedtest ....

[zanieb]

I don't think implicit behavior is great when executing things, for safety and security reasons.

Why not expose script entry points for your modules? https://docs.astral.sh/uv/concepts/projects/#defining-entry-points

[rogerbinns]

I agree with the safety aspect in principle, but in this specific case the user already has explicitly said they are trying to run the provided parameters. Adding more hoops to jump through will just be annoying.

The problem with project.scripts is that it creates new executables that end up in $PATH, in completions, and in a global namespace. My project is python specific and doesn't need to contribute to that pollution.

[zanieb]

end up in $PATH, in completions, and in a global namespace

Fair, but note this isn't the case unless you install the project globally or activate the virtual environment — both of which are not necessary with uv run.

[rogerbinns]

... unless you install the project globally

My project is installed globally on a large number of Linux/BSD distros. I'm left with two choices:

• Add the entry points, and then have every distro maintainer add extra logic in their packaging rules to exclude them when doing system packaging
• Miss out on easy uv run for people using uv.

[zanieb]

I see. Maybe your use-case would be fulfilled by #5903 then. There's also an exploration of module support in #7322 — but there was some complexity in the command line handling. Maybe the solution is a --module flag like we are adding for --script #7739?

[rogerbinns]

I don't have a preference on the solution implementation, as long as the interface is as friendly as python -m module args..., and I'm happy to put whatever uv specific config is needed in pyproject.toml to make that happen.

[zanieb]

Okay thanks for your feedback. @j178 do you see a problem with just doing module: bool instead of module: Option<String>?

[j178]

Seems working 😆 #7754