How to Use uvx to Run Python Tools from Any Git Branch or Commit

Mar 5, 2026

Problem

I found a Python tool on GitHub with a feature I needed, but it was only available on a development branch. The maintainer hadn’t released it yet. I could clone the repo and install it manually, but that seemed like overkill just to test one feature.

Then I discovered uvx can run tools directly from any Git branch, tag, or commit in seconds.

Environment

uv 0.5.0+
Python 3.10+
Git 2.30+

The Solution

The key is the --from flag with a Git URL:

uvx --from git+https://github.com/user/repo@branch-name tool-name

The @ symbol specifies the Git reference - branch, tag, or commit hash.

Run from a Branch

uvx --from git+https://github.com/user/repo@feature-branch tool-name

Run from a Tag

uvx --from git+https://github.com/user/[email protected] tool-name

Run from a Commit

uvx --from git+https://github.com/user/repo@2843b87 tool-name

This downloads the package from Git, creates an ephemeral environment, runs the tool, and caches it for future use.

Real-World Example

I saw this command on Reddit that sparked my interest:

uvx --from git+https://github.com/Zaloog/kanban-tui@lg/independent-board-columns ktui demo

This runs ktui demo from the lg/independent-board-columns branch - a work-in-progress feature branch. The install completed in about 3 seconds.

Why this is useful:

Share work-in-progress with collaborators without releasing
Test your own PRs before merging
Reproduce bugs from specific commits
Try pre-release features

Different Git References

By Branch Name

uvx --from git+https://github.com/astral-sh/ruff@main ruff check .

This runs ruff from the main branch - useful for testing unreleased changes.

By Tag

uvx --from git+https://github.com/pallets/[email protected] click --help

Tags work well for reproducible builds or testing specific releases.

By Full Commit Hash

uvx --from git+https://github.com/org/project@326b9431c761e1ef1e00b9f760d1f654c8db48c6 tool-name

Full hashes ensure exact reproducibility. Short hashes work too:

uvx --from git+https://github.com/org/project@abc123d tool-name

With Subdirectories

Some projects have multiple packages in one repo:

uvx --from git+https://github.com/langchain-ai/langchain#subdirectory=libs/langchain langchain-cli

The #subdirectory= fragment tells uv where to find the package.

How It Works

When I run uvx with --from git+...:

uv resolves the Git URL and fetches the repository
It creates an isolated environment in the cache
Installs the package from the Git source
Runs the command in that environment
Keeps the cache for fast subsequent runs

To pull the latest changes from a branch:

uvx --refresh --from git+https://github.com/user/repo@branch tool-name

Or clear the cache entirely:

uv cache clean

Common Use Cases

Test Your Own PR

uvx --from git+https://github.com/yourname/tool@your-feature-branch tool-name

Share this command in your PR description so reviewers can test it immediately.

Try a Fork

uvx --from git+https://github.com/fork-owner/project@their-branch tool-name

No need to clone or switch remotes - just run from the fork’s branch.

Reproduce a Bug from a Commit

uvx --from git+https://github.com/org/tool@abc123def tool-name --buggy-flag

When someone reports a bug, ask for the commit hash and test it directly.

Run Development Versions

# Latest ruff from main
uvx --from git+https://github.com/astral-sh/ruff@main ruff check .

# Latest black from main
uvx --from git+https://github.com/psf/black@main black .

Extra Options

Add Dependencies

Some tools need extra packages:

uvx --from git+https://github.com/org/project@branch tool-name --with requests --with rich

Specify Python Version

uvx --python 3.11 --from git+https://github.com/org/project@branch tool-name

Install Permanently

uvx creates ephemeral environments. For persistent installation:

uv tool install --from git+https://github.com/org/project@branch tool-name

Then run it anytime:

tool-name

To update later:

uv tool upgrade tool-name

Comparison with Alternatives

Method	Speed	Effort	When to Use
`uvx --from git`	Seconds	Low	One-off testing from branches
`pip install git+...`	Minutes	Medium	Installing into existing env
Clone + pip install	Minutes	High	Need to modify code
`uv tool install --from git`	Seconds	Low	Permanent installation

uvx wins for quick testing. Use uv tool install if you’ll run the tool repeatedly.

Troubleshooting

Git must be installed - uv uses Git to fetch repositories. Make sure git is in your PATH.

Branch names with slashes - Use the full name:

uvx --from git+https://github.com/org/repo@feature/sub-feature tool-name

Private repositories - Use SSH:

uvx --from git+ssh://[email protected]/org/private-repo@branch tool-name

Or configure Git credentials for HTTPS.

Wrong command name - The command name might differ from the package name. Check the package’s pyproject.toml or setup.py for the entry point.

The Reason This Works

uvx uses pip’s VCS (Version Control System) support under the hood. The git+https:// prefix tells pip to fetch from Git instead of PyPI. The @branch-name syntax selects the specific ref.

This is the same mechanism as:

pip install git+https://github.com/user/repo@branch-name

But uvx wraps it with:

Automatic environment creation
Ephemeral execution
Caching
Cleanup

Summary

In this post, I showed how to use uvx to run Python tools from any Git branch, tag, or commit. The key syntax is uvx --from git+https://github.com/user/repo@ref tool-name. This skips the clone-and-install workflow and lets you test development versions in seconds.

The main use cases are testing PRs, trying forks, reproducing bugs from specific commits, and evaluating pre-release features. Use uv tool install instead of uvx if you want permanent installation.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!