Skip to content
Back to search

simple-modern-uv

A powerful, minimal agent skill and template for modern Python projects with uv

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jlevy--simple-modern-uv/badge.svg)](/listings/jlevy--simple-modern-uv)

HTML

<a href="/listings/jlevy--simple-modern-uv"><img src="/api/listings/jlevy--simple-modern-uv/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 480 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![As usual, XKCD has a comic for this](https://imgs.xkcd.com/comics/python_environment.png)](https://xkcd.com/1987/)
  2. (As usual, XKCD has a comic for this.
  3. Appropriately enough, the comic is out of date.)
  4. # simple-modern-uv
  5. [![Follow @ojoshe on X](https://img.shields.io/badge/follow_%40ojoshe-black?logo=x&logoColor=white)](https://x.com/ojoshe)
  6. [![python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
  7. [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
  8. [![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-border.json)](https://github.com/copier-org/copier)
  9. ## What Is This?
  10. **simple-modern-uv** is a minimal, modern **Python project template** for new projects
  11. (Python 3.11–3.14) based on [**uv**](https://docs.astral.sh/uv/). This template aims to
  12. be a good base for serious work but also simple so it’s an easy option for any small
  13. project, like an open source library or tool.
  14. It can also upgrade an existing project to a modern setup: uv, ruff, BasedPyright, and
  15. GitHub Actions, or add only the practices that fit without forcing a full migration.
  16. The [agent skill](#use-with-any-coding-agent) handles each adoption path.
  17. ## Use with Any Coding Agent
  18. Install the [simple-modern-uv skill bundle](skills/simple-modern-uv/SKILL.md) with the
  19. [skills CLI](https://github.com/vercel-labs/skills), then appoint your coding agent to
  20. do the work. The bundle follows the [Agent Skills](https://agentskills.io) open format;
  21. the installer supports Claude Code, Codex, Cursor, Gemini CLI, and other compatible
  22. agents:
  23. ```shell
  24. NPM_CONFIG_IGNORE_SCRIPTS=true NPM_CONFIG_BEFORE=2026-07-31T18:59:05Z \
  25. npx --yes skills@1.5.18 add jlevy/simple-modern-uv \
  26. --skill simple-modern-uv --yes
  27. ```
  28. Then describe the outcome rather than translating it into template commands:
  29. | Goal | Example prompt | Result |
  30. | --- | --- | --- |
  31. | Start fresh | “Start a new Python project called `my-package` using simple-modern-uv.” | A complete, template-managed project |
  32. | Add features ad hoc | “Add simple-modern-uv’s uv lock policy and CI to this repo, but keep its build backend.” | Only the selected, compatible feature bundles |
  33. | Upgrade a project | “Migrate this package from Poetry to simple-modern-uv and preserve its public behavior.” | A full migration with future Copier updates |
  34. | Update later | “Update this project to the latest simple-modern-uv template.” | Upstream changes reconciled with local adaptations |
  35. No installer handy? Tell the agent to fetch the
  36. [`SKILL.md`](skills/simple-modern-uv/SKILL.md) and the directly linked reference for the
  37. selected workflow from the same Git revision, then follow them.
  38. ### Adopt Only What Fits
  39. The skill treats conformance as a design choice, not a pass/fail label:
  40. - **Selective adoption** adds named capabilities without changing unrelated project
  41. choices or claiming Copier ownership.
  42. - **Core toolchain adoption** adds uv, reproducible locking, linting, typing, tests, CI,
  43. and agent guidance while preserving packaging or layout where appropriate.
  44. - **Full template-managed adoption** uses the rendered structure and
  45. `.copier-answers.yml` so future `copier update` runs work.
  46. The agent first audits the repository, then reports what it will adopt unchanged, adapt
  47. to local constraints, preserve, or defer.
  48. Changes to supported Python versions, package layout, build backend, versioning,
  49. licensing, publishing, or CI remain explicit user decisions.
  50. See the procedures for
  51. [selective adoption](skills/simple-modern-uv/references/adopt-selectively.md),
  52. [full migration](skills/simple-modern-uv/references/adopt-existing.md),
  53. [new projects](skills/simple-modern-uv/references/start-new-project.md), and
  54. [template updates](skills/simple-modern-uv/references/update-templated-project.md).
  55. Generated projects are agent-ready too: each includes an
  56. [`AGENTS.md`](template/AGENTS.md.jinja) following the [AGENTS.md](https://agents.md)
  57. standard, with the project’s build, test, and development conventions, plus a
  58. [`CLAUDE.md`](template/CLAUDE.md) that imports it for Claude Code.
  59. To work without an agent, see [How to Use This Template](#how-to-use-this-template).
  60. ## Why a New Python Project Template?
  61. > **The Story So Far**
  62. >
  63. > In the beginning, there was a hack called
  64. > [`setup.py`](https://github.com/pypa/setuptools) for packaging (1990s–2000s) and it
  65. > was not good.
  66. >
  67. > Then there arose [`virtualenv`](https://github.com/pypa/virtualenv),
  68. > [`pip`](https://github.com/pypa/pip), and `requirements.txt` for isolated environments
  69. > (2008–2011). Yet confusion still reigned.
  70. >
  71. > Meanwhile, [`conda`](https://github.com/conda/conda),
  72. > [`pyenv`](https://github.com/pyenv/pyenv), [`brew`](https://github.com/Homebrew/brew),
  73. > and [`PyInstaller`](https://github.com/pyinstaller/pyinstaller) vied to rule the
  74. > system installations (2010s).
  75. >
  76. > Years of dissatisfaction led to the spread of a new religion,
  77. > [`pyproject.toml`](https://github.com/pypa/pyproject.toml).
  78. > Adherents of [`poetry`](https://github.com/python-poetry/poetry),
  79. > [`pipenv`](https://github.com/pypa/pipenv), and [`pipx`](https://github.com/pypa/pipx)
  80. > promised peace and prosperity (2020s) yet somehow, life felt mostly the same.
  81. >
  82. > Then AI robots began to invade.
  83. > Rebel forces [`uv`](https://github.com/astral-sh/uv) and
  84. > [`pixi`](https://github.com/prefix-dev/pixi) aligned with Rust gathered strength …
  85. Apologies for the digression.
  86. The point is that unfortunately, the accidents of history make it quite confusing to
  87. learn best practices for setting up Python projects and dependencies.
  88. But it shouldn’t have to be this difficult, especially since uv has now significantly
  89. simplified Python dev tooling.
  90. If you haven’t switched to uv, I can say I too was a little hesitant.
  91. It’s often possible to switch dev tooling prematurely because the new tool is shiny and
  92. exciting. But the advantages of uv have become too numerous to ignore.
  93. [This article](https://www.bitecode.dev/p/a-year-of-uv-pros-cons-and-should) (Feb 2025)
  94. has a good overview.
  95. This is the template I now use myself as I have been migrating from Poetry to uv for
  96. several projects. It’s new but it’s working well.
  97. ## But I Don’t Like Templates
  98. A lot of more senior engineers have justified hesitancy about templates.
  99. Templates can be a real problem if they add mindless, unexamined complexity.
  100. But if done carefully, I think they are better than official docs (they show real-world
  101. code you can adapt, instead of leaving you to figure out each tool choice and setting)
  102. or blog posts (that are typically not maintained or updated).
  103. I think a good project template should be **3 Ms: minimalist, modern, and maintained**.
  104. I looked at [other templates](#alternatives) but wanted one that was modern and “done
  105. right” but *absolutely as simple as possible*. Few existing templates seem to be both
  106. simple and use the newest generation of tools and best practices.
  107. The template is short enough to read and understand in about 10 minutes.
  108. It’s **only ~300 lines of code** so you can just look at it, use it, and change what you
  109. want without fuss.
  110. Because this template is minimal, you can always start with it and then pull in other
  111. tools and features if you want them.
  112. (In fact, even if you don’t like this template, you might want to use it as inspiration
  113. for your *own* Copier template, to take advantage of the Copier update workflow
  114. discussed next.)
  115. ## Why Use Copier?
  116. One other benefit of this template is it uses
  117. [**copier**](https://github.com/copier-org/copier).
  118. Unlike many previous project template tools, Copier lets you
  119. [pull future template changes](#updating-your-project-template) back into your
  120. instantiated copy at any time.
  121. You can start a project now, then if this template improves or is updated with other
  122. tools, you can pull those improvements back into your project, much like a git merge.
  123. You could even fork this repo yourself, then build your own forked template, and
  124. maintain it yourself.
  125. If you’re not familiar with Copier, take a moment to understand the
  126. [update feature](#updating-your-project-template).
  127. Then the options below will make sense.
  128. I put a few more thoughts on why a workflow like this is underrated in
  129. [a Twitter thread](https://x.com/ojoshe/status/1896696860297019733).
  130. ## What Tools Are in This Template?
  131. simple-modern-uv uses the tools I’ve come to think are best for new projects:
  132. - [**uv**](https://github.com/astral-sh/uv) for project setup and dependencies.
  133. There is also a simple makefile for dev workflows, but it simply is a convenience for
  134. running uv commands.
  135. - [**ruff**](https://github.com/charliermarsh/ruff) for modern linting and formatting.
  136. Previously, [black](https://github.com/psf/black) was the definitive formatting tool,
  137. but ruff now handles linting and fast, black-compatible formatting.
  138. - [**GitHub Actions**](https://github.com/actions/setup-python) for CI and publishing
  139. workflows.
  140. - [**Dynamic versioning**](https://github.com/ninoseki/uv-dynamic-versioning/) so
  141. release and package publication is as simple as creating a tag/release on GitHub (no
  142. machinery needed to manually bump versions and commit files every release).
  143. - Workflows for **packaging and publishing to PyPI** with uv.
  144. This has always been more confusing than it should be.
  145. The
  146. [official docs](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
  147. about packaging are several pages long, and then even
  148. [toy tutorials](https://realpython.com/pypi-publish-python-package/) about publishing
  149. are even longer. This template makes all of that basically automatic with uv, GitHub
  150. Actions, and dynamic versioning.
  151. - Type checking with [**BasedPyright**](https://github.com/detachhead/basedpyright).
  152. (See below for more on this.)
  153. - [**Pytest**](https://github.com/pytest-dev/pytest) for tests (with the excellent
  154. plugin [**pytest-sugar**](https://github.com/Teemu/pytest-sugar) for faster errors and
  155. nicer output).
  156. - [**codespell**](https://github.com/codespell-project/codespell) for drop-in spell
  157. checking.
  158. ## Starter Docs
  159. The template includes a few **starter docs** for you, collaborators, and users:
  160. - [README.md](https://github.com/jlevy/simple-modern-uv/blob/main/template/README.md.jinja)
  161. is a placeholder for your project readme.
  162. - [installation.md](https://github.com/jlevy/simple-modern-uv/blob/main/template/docs/installation.md)
  163. has brief reminders on the modern ways to install uv and Python.
  164. - [development.md](https://github.com/jlevy/simple-modern-uv/blob/main/template/docs/development.md.jinja)
  165. covers basic developer workflows.
  166. - [publishing.md](https://github.com/jlevy/simple-modern-uv/blob/main/template/docs/publishing.md)
  167. covers how to publish your project to PyPI.
  168. If you haven’t done it before, publishing a package to PyPI can be a bit confusing,
  169. especially because the
  170. [official Python docs](https://packaging.python.org/en/latest/guides/section-build-and-publish/)
  171. cover older and more complex workflows.
  172. Be sure to check `publishing.md` for a modern and simple way that uses uv and GitHub
  173. actions.
  174. You can edit or delete these, but typically it’s sufficient to just edit the README.md.
  175. It helps to have the others in separate files so they get updated whenever you update
  176. the template.
  177. ## What’s the Best Python Type Checker?
  178. The choice of what tool to use for type checking deserves some explanation.
  179. This seems to be a confusing area.
  180. Like many, I’d previously been using [Mypy](https://github.com/python/mypy), the OG type
  181. checker for Python. Mypy has since been enhanced with
  182. [BasedMypy](https://github.com/KotlinIsland/basedmypy).
  183. The other popular alternative is Microsoft’s
  184. [Pyright](https://github.com/microsoft/pyright).
  185. And it has a newer extension and fork called
  186. [BasedPyright](https://github.com/DetachHead/basedpyright).
  187. All of these work in build systems.
  188. But this is a choice not just of build tooling: it is far preferable to have your type
  189. checker warnings align with your IDE warnings.
  190. With the rises of AI-powered IDEs like Cursor and Windsurf that are VSCode extensions,
  191. it seems like type checking support as a VSCode-compatible extension is essential.
  192. However, Microsoft’s popular
  193. [Mypy VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-python.mypy-type-checker)
  194. is licensed only for use in VSCode (not other IDEs) and
  195. [sometimes](https://forum.cursor.com/t/pylance-server-fails-to-initialize-due-to-licensing-restriction/48548)
  196. [refuses](https://forum.cursor.com/t/does-pylance-just-not-work-with-cursor-how-to-get-imports-in-quick-fix-menu/5747)
  197. to work in Cursor. [Cursor’s docs](https://docs.cursor.com/guides/languages/python)
  198. suggest Mypy but don’t suggest a VSCode extension.
  199. After some experimentation, I found
  200. [BasedPyright](https://github.com/detachhead/basedpyright) to be a credible improvement
  201. on [Pyright](https://github.com/microsoft/pyright).
  202. BasedPyright is well maintained, is faster than Mypy, and has a good
  203. [VSCode extension](https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright)
  204. that works with Cursor and other VSCode forks.
  205. So I have now switched this template to use BasedPyright.
  206. (But please file an issue if you have better suggestions.)
  207. One newer option worth watching is [**ty**](https://github.com/astral-sh/ty), Astral’s
  208. own type checker (from the makers of uv and ruff), written in Rust.
  209. It’s extremely fast, often 10–60x faster than Mypy or Pyright, and ships a language
  210. server with extensions for VSCode, PyCharm, Neovim, and other editors.
  211. As of mid-2026 it’s still in [beta](https://astral.sh/blog/ty) and on `0.0.x`
  212. versioning, so its API and diagnostics can change between releases.
  213. It also doesn’t yet match BasedPyright on
  214. [typing-spec coverage](https://pydevtools.com/handbook/explanation/how-do-mypy-pyright-and-ty-compare/)
  215. or strictness: Astral is still filling in the long tail of typing features and
  216. first-class support for libraries like Pydantic and Django.
  217. For now this template stays on BasedPyright for its maturity and more complete checks.
  218. But ty is a strong contender that fits naturally with uv, and this recommendation may
  219. change once ty reaches comparable coverage.
  220. For the full comparison and the objective conformance data behind this, see the
  221. [type-checker research doc](docs/project/research/research-python-type-checkers.md).
  222. ## What Does This Template Not Include?
  223. The template doesn’t have lots of options or try to use every bell and whistle.
  224. It just adds the above essentials.
  225. This template **does not** handle:
  226. - Using Docker
  227. - Private or enterprise package repositories (but you can add this; see
  228. [uv’s docs on alternative indexes](https://docs.astral.sh/uv/guides/integration/alternative-indexes/))
  229. - Building websites or docs, e.g. with [mkdocs](https://github.com/mkdocs/mkdocs)
  230. - Using [Conda](https://github.com/conda/conda) for dependencies (but note many deep
  231. learning libraries like PyTorch now support pip so this isn’t as necessary as often as
  232. it used to be)
  233. - Using a code repo or build system that isn’t GitHub and GitHub Actions
  234. - Boilerplate docs or project management of any kind, like issue templates, contributing
  235. guidelines, code of conduct, etc.
  236. Docker and private repo use can be added by you manually to the project after you get
  237. started. Similarly, you can change CI/CD workflows if you are not using GitHub or GitHub
  238. Actions or PyPI.
  239. Also see [below](#alternatives) for other templates you can look at or use as
  240. references.
  241. ## How to Use This Template
  242. License and publishing are template questions, not hand edits: `package_license`
  243. (default MIT; also Apache-2.0, BSD-3-Clause, AGPL-3.0-or-later, Proprietary, or None to
  244. decide later) and `publish_to_pypi` (answer no for a private package; the publish
  245. workflow and docs are then omitted).
  246. Answer them at render time or change them later with
  247. `uvx --exclude-newer "14 days" copier@9.17.0 update --data package_license=…`; see the
  248. skill’s [customize guide](skills/simple-modern-uv/references/customize.md) for details.
  249. Prefer re-answering over hand-deleting generated files like `publish.yml`, so future
  250. `copier update` runs stay consistent.
  251. The template can be used in three ways.
  252. Option 1 is the quickest: your AI coding agent gathers the project details and does the
  253. setup. Option 2 is the normal way to use a Copier template by hand.
  254. Option 3 is handy if you prefer a GitHub template.
  255. ### Option 1: Use Your Agent (Recommended)
  256. Install the [agent skill](skills/simple-modern-uv/SKILL.md) and ask your agent.
  257. [Use with Any Coding Agent](#use-with-any-coding-agent) has the exact installation
  258. command, four workflow prompts, and adoption boundaries.
  259. The agent inspects the repo, confirms only material choices, performs the work
  260. non-interactively, and reports the resulting adoption level and validation.
  261. ### Option 2: Use `copier` and `git` Yourself
  262. This template uses [Copier](https://github.com/copier-org/copier), which seems like the
  263. best tool nowadays for project templates.
  264. Using Copier is the recommended approach since it then lets you instantiate the template
  265. variables and makes future updates possible.
  266. But it requires a few more commands.
  267. To create a new project repo with the reviewed Copier version:
  268. ```shell
  269. # Change dirs to the place you want the new GitHub repo to be.
  270. cd ~/projects/github # Wherever you do your project work.
  271. # Clone this template under the supply-chain cool-off. This does everything!
  272. # It will fetch from this GitHub repo and create a new directory
  273. # with whatever name you put below:
  274. uvx --exclude-newer "14 days" copier@9.17.0 copy \
  275. gh:jlevy/simple-modern-uv YOURNEWREPO
  276. # Then follow the instructions.
  277. ```
  278. You can enter names for the project, description, etc., or just press enter and later
  279. look for `changeme` in the code.
  280. Once you have the template set up, you will need to check the code into Git for uv to
  281. work.
  282. [Create a new GitHub repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository),
  283. making sure to create it as an **empty repo** (don’t add a README, .gitignore, or
  284. license, since the template already provides these), and add your initial code:
  285. ```shell
  286. cd PROJECT
  287. git init --initial-branch=main
  288. git add .
  289. git commit -m "Initial commit from simple-modern-uv."
  290. # Sync after the first commit so dynamic versioning gives the editable install
  291. # a real version (not 0.0.0). This creates uv.lock; commit it so CI installs
  292. # reproducibly with --locked and verifies the lockfile is current.
  293. make install
  294. git add uv.lock
  295. git commit -m "Add uv.lock."
  296. # Create repo on GitHub.
  297. git remote add origin git@github.com:OWNER/PROJECT.git # or https://github.com/...
  298. git push -u origin main
  299. ```
  300. ### Option 3: Use the GitHub Template
  301. If you prefer you can click the **use this template** on
  302. [**this repository**](https://github.com/jlevy/simple-modern-uv-template), which is the
  303. current output of this template.
  304. Go there and hit the “Use this template” button.
  305. Once you have the code, search for **`changeme`** for all field names like project name,
  306. author, etc. You want to do this to the `.copier-answers.yml` file as well.
  307. You will also want to check the license/copyright.
  308. ## Updating Your Project Template
  309. If you use Option 1 or Option 2 or if you pick Option 3 and correctly fill in your
  310. `.copier-answers.yml` file, you have the option to update your project with any future
  311. updates to this template at any time.
  312. When `.copier-answers.yml` records your project values, you can
  313. [update your project](https://copier.readthedocs.io/en/latest/updating/) to reflect any
  314. changes to this template by running `copier update`.
  315. ## Alternatives
  316. There are a couple other good uv templates, especially
  317. [**cookiecutter-uv**](https://github.com/fpgmaas/cookiecutter-uv) and
  318. [**copier-uv**](https://github.com/pawamoy/copier-uv) you may wish to consider.
  319. This template takes a somewhat different philosophy.
  320. I found existing templates to have machinery or files you often don’t need.
  321. And it’s hard to maintain a complex template repo.
  322. This is intended instead to be a very simple template.
  323. You can always add to it if you want.
  324. There is also [**uv-migrator**](https://github.com/stvnksslr/uv-migrator) to help you
  325. migrate projects to uv.
  326. Previously, [Poetry](https://python-poetry.org/docs/basic-usage/) was probably the best
  327. modern tool for managing dependencies.
  328. It is not as new as uv and arguably more mature (it just hit version 2.0). In fact, this
  329. template is based on my earlier Poetry template,
  330. [simple-modern-poetry](https://github.com/jlevy/simple-modern-poetry).
  331. Another great resource to check is
  332. [**python-blueprint**](https://github.com/johnthagen/python-blueprint), which is a more
  333. established template with an excellent overview of other standard Python project best
  334. practices. It uses [Poetry](https://python-poetry.org/docs/basic-usage/),
  335. [nox](https://github.com/wntrblm/nox),
  336. [Material for Mkdocs](https://github.com/squidfunk/mkdocs-material), and Docker.
  337. For [Conda](https://github.com/conda/conda) dependencies, also consider the newer
  338. [**pixi**](https://github.com/prefix-dev/pixi/) package manager.
  339. ## Supply Chain Hardening
  340. Dependencies are an attack surface.
  341. The best resource on this is
  342. [**supply-chain-hardening**](https://github.com/jlevy/supply-chain-hardening), a concise
  343. guidebook of concrete recipes for npm, PyPI, and other ecosystems.
  344. **If you use this template, follow it.** Its key defaults, which this template also
  345. follows:
  346. - **Cooling-off period:** Don’t install or upgrade to a release less than 14 days old
  347. (most malicious publishes are caught within days).
  348. uv supports a relative
  349. [dependency cooldown](https://docs.astral.sh/uv/concepts/resolution/#dependency-cooldowns)
  350. such as `"14 days"`; this template sets it in generated `uv.toml`, CI, and the
  351. Makefile. Standard workflows select that checked-in file explicitly so ambient user
  352. settings cannot make `uv.lock` nonportable.
  353. - **Vet what you add:** Only add dependencies you can verify upstream, and prefer a
  354. little first-party code over pulling in a new dependency.
  355. - **Pin and lock:** Commit your `uv.lock` and pin GitHub Actions to full commit SHAs.
  356. Treat a version tag as immutable only after verifying that release state through the
  357. GitHub API.
  358. See [updating.md](updating.md#supply-chain-hygiene) for how this template applies these.
  359. ## Maintaining and Releasing This Template
  360. If you’re contributing to this template or forking it for your own use, see
  361. [**updating.md**](updating.md) for the full process to check for new versions, update
  362. the template, verify changes in a downstream project, and publish a GitHub Release.
  363. The GitHub Release creates the version tag only after the downstream gate passes; do not
  364. create a bare tag immediately after merging the template PR. Maintainer research, frozen
  365. supply-chain evidence, and implementation records are indexed in the
  366. [project documentation](docs/project/README.md).
  367. ## Contributing
  368. Please [file an issue](https://github.com/jlevy/simple-modern-uv/issues) with any bugs,
  369. suggestions, or other ideas.
  370. PRs welcome on [this repository](https://github.com/jlevy/simple-modern-uv) (not on the
  371. GitHub template repo, which mirrors this one).
  372. <!-- This document follows common-doc-guidelines.md.
  373. See github.com/jlevy/practical-prose and review guidelines before editing.
  374. -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.