Here’s a short guide (targeted primarily at myself) on how to get a project from Github (or some other git-based repository) onto my machine. This guide assumes you have git and uv installed and added to your path. Also, the secret to understanding uv is seeing the lockfile as foundational rather than the packages currently installed. I also have never yet committed my lockfile.
First, we need to use git to get a local copy of the project: git clone https://...
Second, let’s open up that directory (cd repo_name) and install the dependencies:
uv sync: a reasonable default; n.b., this will install in editable mode (cf.pip install -e .)uv pip install -e .: if you haveproject.scriptsin your pyproject.toml which need to be run, use this instead; apparently,uvis not able to install scriptsuv sync --locked: if you’ve committed your lockfile and want to precisely match these versions (e.g., for a web app where specific versions are required across multiple systems)uv sync --no-editable: equivalent otpip install .(i.e., without the-eeditable flag)
If we then need to upgrade a package, we will need to update the lockfile and then run uv sync to install the new version:
uv lock --upgrade: upgrade alluv lock --upgrade-package polars: upgrade just polars (or, use--upgrade-packagemultiple times for upgrading specific packages)uv sync: must use this to ‘sync’ the environment to the lockfile
To add a package to the lockfile from Github, use:
uv add 'jsonl-index @ git+https://github.com/.../jsonl-index.git- Add
@branchor@versionor@commit(e.g.,@master,@0.1.1, or@54321) after thejsonl-index.gitportion of the git+https url to select a specific version
- Add
For running scripts, I’m still not quite sure what the context for this is (maybe, being able to share a script without the user having Python installed, and everything is easily managed with just uv installed): https://docs.astral.sh/uv/guides/scripts/ — something to explore more!