The singular purpose of runvenv is to go through a useful ordered search to find a named environment directory, and then run that python executable so that the python script ends up within the environment. Python detects where it is run from, so as long as the right one is executed, the rest of the environment is used properly.
This supports a bunch of approaches. For example, it works for making scripts with a named environment right in the same directory of the script, and then it will find that environment without activating anything, regardless of the current working directory, and even if the script is run from a symlink. It also supports a user level collection of venvs, and a system level collection of venvs. And if it can't find those, it goes through all of the places conda environments are typically found, and looks for a matching conda environment to use.
I've been using it a good bit since I wrote it, and I feel like it's one of those things that "just works". It has been a game changer for me in making little python scripts with a python environment dependency, since I can just drop the name of the environment in the shebang line, and it will "do the right thing", find it, and use it to run the python code.
There are a few other tools like "uv" and "pipx" that can handle shebang lines properly, within their own environment ecosystem. But this one works flexibly for shebangs with standard venvs project-level or shared, or with the conda environments I encounter regularly in data science. I put a bunch of usage examples in the README.
This "should" be cross-platform, as a good attempt was made, but I would appreciate some feedback on this from people trying it out, as platforms can be quite heterogeneous and there are surely some cases to account for.
Personally I'm not sure I like the idea of searching based on a folder name, as opposed to having some explicit registry of venvs. But this does seem to be more functionality than the existing options offer.
Out of curiousity, how do you typically make and organize your venvs?
If it's a one-off environment for one program, I'll usually just make a venv and put it right next to the script. But the problem is I don't want the clutter of an environment in places that are in my executable path. So if I have something like a repo directory that has a python program and an environment, or ~/python with a python program and an environment next to it, then I just drop a symlink in ~/bin/ to the executable script, and now runvenv will follow that symlink, find the venv next to the script, and run it. So it kind of separates it. I can make my environments however I want or wherever I want with conda or venv, and the scripts using them are still directly executable. Either by adjacency to the script, or a symlink in ~/.venv to them (if I didn't make them directly in there). It doesn't functionally matter if they're accessed via a symlink, because the runpip tool takes care of handling that properly.