Updating environments¶
karotte update brings an environment up to the latest Karotte release and its templates.
It merges the template changes into your files, so your own edits survive.
Run it from the environment's directory:
uvx runs the newest Karotte.
You can also pass the environment's directory: uvx karotte update path/to/my_env.
Commit your work first, so that git diff shows what the update changed.
karotte update needs git on your PATH.
How it works¶
- Karotte checks the
UV_INDEX*variables and runs each update migration'sprepare(see Plugins). Then it reads.manifest.json(see The manifest) to find the Karotte version and templates the environment was made with. - It looks up the newest Karotte release on the environment's package indexes. There is nothing to do if all of these hold: that release is the version in the manifest, no template package has a newer release, and you aren't adding a template.
- It renders the environment twice into a temporary directory, both times with the manifest's templates. The first render uses the old Karotte and is called the baseline. The second uses the new Karotte and is called the target.
- It runs each update migration's
migrateon the baseline and your environment. Then it applies the difference between the two renders to your environment, one file at a time. - It writes the new version, templates and template packages to the manifest.
- It re-locks the environment and any venv whose
pyproject.tomlchanged.
In step 4, each file is handled like this:
| Template change | Your file | Result |
|---|---|---|
| Changed text file | Present | 3-way merge with git merge-file. Overlapping changes become a conflict. |
| Changed binary file | Present | Replaced with the template's version. |
| File in both renders | Deleted by you | Recreated, unless it's under do_not_recreate_if_deleted. |
| New file | Absent | Added, unless it's under do_not_recreate_if_deleted. |
| New file | Present | Replaced with the template's version. |
| Removed file | Present | Deleted. |
Warning
If the template no longer ships a file, the update deletes it from your environment, even if you changed it.
Check git status after an update.
Karotte never merges .git, .venv, __pycache__, .ruff_cache, uv.lock or .manifest.json.
The manifest's do_not_recreate_if_deleted list gets merged too.
Paths that a new template version adds to its list are added to yours.
Paths that it drops from its list are removed from yours.
Your own edits to the list stay.
Conflicts¶
At the end, karotte update lists the files that have conflicts.
Each conflict has the usual markers, with your version first and the template's version second.
Edit each file until it looks the way you want, and remove the markers.
Sometimes git can't merge a file at all.
In that case Karotte keeps your version, reports the file as a conflict, and logs the reason.
You then need to apply the template's change by hand.
Re-locking¶
If pyproject.toml merged without conflicts, Karotte runs:
It adds an extra --upgrade-package for each template package.
A plain uv lock would keep the Karotte version that's already in the lock, and then the lock and the manifest would disagree.
Karotte also runs uv lock in each venvs/*/ directory whose pyproject.toml the merge added or changed.
If pyproject.toml has conflicts, it isn't valid TOML.
In that case Karotte skips the re-lock and prints the command for you to run.
Once you've resolved the conflicts, run that command yourself.
Also run uv lock in each venvs/*/ directory that had conflicts.
Adding a template¶
To add a template to an environment that was made without it, pass --add-template:
Karotte renders the baseline with the manifest's templates, and the target with the new template added.
As a result, the new template's files arrive as additions, and its changes to existing files arrive as merges.
Karotte resolves the new template's requires too, and records the result in the manifest.
You can pass --add-template more than once.
If you name a template that's already in the manifest, nothing happens.
If you name the same template twice, you get an error.
The update also brings the environment up to the latest Karotte.
Templates from other packages¶
Karotte renders templates from a template package with that package installed next to Karotte.
The manifest records the package in extra_deps, and karotte update installs the package's newest release for the target render.
If a recorded package isn't installed next to the Karotte you're running, karotte update restarts itself with that package.
Sometimes the manifest doesn't record a template's package yet, for example when you add the template with --add-template.
In that case, pass the package with --with:
When update refuses to run¶
- One of
UV_INDEX,UV_DEFAULT_INDEX,UV_INDEX_URLorUV_EXTRA_INDEX_URLis set. uv prefers these over the indexes in the environment'spyproject.toml, so the update would lock against the wrong index. Unset them. - The environment has no
.manifest.json. - Karotte can't find the newest release, or it can't render one of the versions.
The error includes uv's output.
If a template isn't found, pass the package that provides it with
--with.
Karotte looks up releases on the environment's own non-explicit [[tool.uv.index]] entries.
It uses the same 7-day age limit as the environment's exclude-newer setting.
Karotte itself and template packages are exempt from that limit.
Updating past the fastmcp 4 upgrade¶
Karotte now uses fastmcp 4 and mcp 2.
karotte update doesn't rewrite your own code, so check these by hand.
fastmcp.tools.toolis gone. ImportToolResultfromfastmcp.tools. Tools that still use the old path keep loading, but Karotte logs a warning for each run.- The mcp types (
CallToolResult,TextContent,ImageContent,Tool) use snake_case attributes. Code that reads a tool result, such as a scorer or a hook, needs the new names:
| Before | After |
|---|---|
isError |
is_error |
structuredContent |
structured_content |
mimeType |
mime_type |
inputSchema |
input_schema |
The constructors still accept the old names, so the old names only fail when you read them, with an AttributeError.
- In stored transcripts, a tool result's meta key is now _meta, on the result and on each content block, and each result has resultType.
Karotte still loads transcripts written before the change.
Check any code of your own that reads transcript JSON.