What changed, and why it matters
This commit only updates developer documentation, replacing instructions that mentioned the Poetry Python tool with instructions for the uv Python tool. No code, dependencies, or security behavior changed.
No security action needed; this is a routine documentation maintenance change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff modifies four Markdown files (CONTRIBUTING.md, README.md, firmware/font/README.md, i18n/README.md) to substitute poetry commands with equivalent uv commands and update related prose. There are no source-code, build-script, lock-file, or configuration changes. Nothing in the diff affects runtime behavior, cryptography, firmware flashing, or the attack surface.
Changed components
Inspect captured patch +43 / −51
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0c98a4b..1d5534d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -142,7 +142,7 @@ to reviewers with proven commitment or domain expertise.
## Coding conventions
A few rules keep the code readable and maintainable. Most are checked by
-`poetry run poe lint` and `poetry run poe format`, and enforced by CI.
+`uv run poe lint` and `uv run poe format`, and enforced by CI.
### Python
@@ -185,7 +185,7 @@ rules enforced by CI:
## Testing
We aim for high test coverage (95% or more) on each PR. Run the tests with
-`poetry run poe test`, and list all available tasks with `poetry run poe`.
+`uv run poe test`, and list all available tasks with `uv run poe`.
---
diff --git a/README.md b/README.md
index 8690e49..7d205b9 100644
--- a/README.md
+++ b/README.md
@@ -66,61 +66,53 @@ To build and flash the firmware:
The first time, the build can take around an hour or so to complete. Subsequent builds should take only a few minutes. If all goes well, you should see a new `build` folder containing `firmware.bin` and `kboot.kfpkg` files when the build completes.
## Install Krux and dev tools
-Krux uses [Poetry](https://python-poetry.org/) as Python packaging and dependency management. This cmd installs development dependencies like [embit](https://github.com/diybitcoinhardware/embit), [ur](https://github.com/selfcustody/foundation-ur-py) and [urtypes](https://github.com/selfcustody/urtypes), and tools to run [tests](https://docs.pytest.org), review code with [pylint](https://pypi.org/project/pylint/), format code with [black](https://github.com/psf/black) and a lib to help handle i18n translations.
+Krux uses [uv](https://docs.astral.sh/uv/) for Python packaging and environment management. Install uv by following its [installation guide](https://docs.astral.sh/uv/getting-started/installation/), then sync the project to install runtime deps ([embit](https://github.com/diybitcoinhardware/embit), [ur](https://github.com/selfcustody/foundation-ur-py), [urtypes](https://github.com/selfcustody/urtypes)) along with the `dev` group ([pytest](https://docs.pytest.org), [pylint](https://pypi.org/project/pylint/), [black](https://github.com/psf/black) and i18n helpers):
```bash
-pip install poetry
-poetry install
+uv sync
```
-If you have a problem installing Poetry on Linux OS:
-```bash
-# we considered the name of the venv .krux
-python -m venv .krux
-source .krux/bin/activate
-```
-The result will be something like:
-```bash
-(.krux) username:~/directory name$
-```
-Now you can run normaly the pip of the poetry:
+`uv sync` creates a `.venv` in the project root, resolves `uv.lock` if needed, and installs everything — this is the day-to-day command. When dependencies in `pyproject.toml` change but you only want to refresh `uv.lock` without touching the venv, run `uv lock` instead; `uv sync` will then pick the new pins on its next run.
+
+> **CI uses `uv sync --frozen`** The workflows refuse to silently re-resolve when `uv.lock` drifts (we value a lot reproducible builds). Whenever you edit `pyproject.toml` (add, remove, or bump a dependency), run `uv lock` (or `uv sync`) and commit `uv.lock` (in same change). Otherwise CI will fail.
+
+### Migrating from a previous Poetry clone
+If your clone was set up with Poetry, remove the old environment before the first `uv sync` so the two managers do not shadow each other:
```bash
-pip install poetry
-poetry install
+rm -rf .venv poetry.lock
+uv sync
```
-Note: when changing the dependencies in `pyptoject.toml` you need to generate a new `poetry.lock` file using the cmd: `poetry lock --no-update`.
-
## Format code
```bash
-poetry run poe format
+uv run poe format
```
## Review code
```bash
-poetry run poe lint
+uv run poe lint
```
## Run tests with coverage
```bash
-poetry run poe test
+uv run poe test
```
Note: The coverage report will be created at the `htmlcov` folder `file:///path/to/krux/htmlcov/index.html`.
For more verbose output (e.g., to see the output of print statements):
```bash
-poetry run poe test-verbose
+uv run poe test-verbose
```
To run just a specific test from a specific file:
```bash
-poetry run pytest --cache-clear ./tests/pages/test_login.py -k 'test_load_key_from_hexadecimal'
+uv run pytest --cache-clear ./tests/pages/test_login.py -k 'test_load_key_from_hexadecimal'
```
## Use the Python interpreter (REPL)
This is useful for rapid development of non-visual code:
```bash
-poetry run python
+uv run python
```
```
Python 3.9.1
@@ -134,37 +126,37 @@ Type "help", "copyright", "credits" or "license" for more information.
## Run the device simulator
This is useful for rapid code development that utilizes UI/UX. It is also good for newcomers to try Krux before purchasing a device. However, the simulator does not behave exactly as the HW device and may not have all features implemented (e.g. scanning via camera a TinySeed currently only works on the HW device).
-Before executing, make sure you have installed the poetry extras:
+Before executing, make sure you have synced the simulator extras:
```bash
-# This cmd will uninstall other extras
-poetry install --extras simulator
+# This cmd installs the simulator extras alongside the dev group
+uv sync --extra simulator
# To install all extras, use:
-poetry install --all-extras
+uv sync --all-extras
```
Run the simulator:
```bash
# Run simulator with the touch device Amigo, then use mouse to navigate
-poetry run poe simulator
+uv run poe simulator
# Run simulator with SD enabled (folder `simulator/sd`) on the small button-only device M5stickV, then use keyboard (arrow keys UP or DOWN and ENTER)
-poetry run poe simulator-m5stickv --sd
+uv run poe simulator-m5stickv --sd
# Run simulator on the device dock, then use keyboard (arrow keys UP or DOWN and ENTER)
-poetry run poe simulator-dock
+uv run poe simulator-dock
# Run simulator with the touch device yahboom, then use mouse to navigate
-poetry run poe simulator-yahboom
+uv run poe simulator-yahboom
# Run simulator on the device cube, then use keyboard (arrow keys UP or DOWN and ENTER)
-poetry run poe simulator-cube
+uv run poe simulator-cube
# Run simulator with the touch device wonderMV, then use mouse to navigate
-poetry run poe simulator-wonder-mv
+uv run poe simulator-wonder-mv
# Run simulator with the touch device tzt, then use mouse to navigate
-poetry run poe simulator-tzt
+uv run poe simulator-tzt
```
Note: With emulated SD card it is possible to store settings, encrypted mnemonics, also drop and sign PSBTs. After some time running, the simulator may become slow. If that happens, just close and open again!
@@ -192,10 +184,10 @@ cd simulator
./generate-all-screenshots.sh
# Run a specific sequence for a specific device's with SD enabled (folder `simulator/sd`)
-poetry run poe simulator --sequence sequences/about.txt --sd
+uv run poe simulator --sequence sequences/about.txt --sd
# Sequence screenshots are scaled to fit in docs. Use --no-screenshot-scale to get full size
-poetry run poe simulator --sequence sequences/home-options.txt --no-screenshot-scale
+uv run poe simulator --sequence sequences/home-options.txt --no-screenshot-scale
```
## Live debug a device (Linux)
@@ -250,19 +242,19 @@ The project has lots of translations [here](i18n/translations), if you add new e
```bash
# Clean unused translations:
-poetry run poe i18n clean
+uv run poe i18n clean
# Create a new translation file in JSON:
-poetry run poe i18n new tr-TR
+uv run poe i18n new tr-TR
# Make sure all files have this new translated message:
-poetry run poe i18n validate
+uv run poe i18n validate
# Format translation files properly:
-poetry run poe i18n prettify
+uv run poe i18n prettify
# Create the compiled table for krux translations.py
-poetry run poe i18n bake
+uv run poe i18n bake
```
## Fonts
@@ -272,21 +264,21 @@ Learn about how to setup fonts [here](firmware/font/README.md)
Use [this script](firmware/scripts/rgbconv.py) to generate device compatible colors from RGB values (usefull for color themes).
## Documentation
-Before change documentation, and run the mkdocs server, make sure you have installed the poetry extras:
+Before change documentation, and run the mkdocs server, make sure you have synced the docs extras:
```bash
-# This cmd will uninstall other extras
-poetry install --extras docs
+# This cmd installs the docs extras alongside the dev group
+uv sync --extra docs
# To install all extras, use:
-poetry install --all-extras
+uv sync --all-extras
```
To change lateral and upper menus on documentation, see `mkdocs.yml` file on `nav` section. To create or edit translations (TODO: need help!), read [here](i18n/README.md).
Create the documentation site locally - `http://127.0.0.1:8000/krux/`:
```bash
-poetry run poe docs
+uv run poe docs
```
# Inspired by these similar projects
diff --git a/firmware/font/README.md b/firmware/font/README.md
index e329951..4328449 100644
--- a/firmware/font/README.md
+++ b/firmware/font/README.md
@@ -3,7 +3,7 @@ Krux uses a [custom fork](https://github.com/bachan/terminus-font-vietnamese) of
To rebuild the font for all devices, run:
```python
-poetry run python bdftokff.py True
+uv run python bdftokff.py True
```
If the `True` argument was passed, the Python script will automatically overwrite the contents of the `font_device.h` file in each of the projects `../MaixPy/projects/*/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h`, otherwise the script will produce 3 files: `m5stickv_font_device.h`, `amigo_font_device.h` and `bit_dock_yahboom_font_device.h`. Use these files to manually replace the contents of the `font_device.h` file in each of your projects.
diff --git a/i18n/README.md b/i18n/README.md
index 70243ad..bf8112c 100644
--- a/i18n/README.md
+++ b/i18n/README.md
@@ -16,7 +16,7 @@ Add a file in format `xy-WZ.json` in [translations](./translations), where `xy`
Execute:
```bash
-poetry install --extras docs
+uv sync --extra docs
```
### Configure translation
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.