FAQ & Troubleshooting

`uv sync --dev` created `.venv`, but the shell is not activated

uv sync installs the environment, but it does not automatically source it.

Activate it manually:

source .venv/bin/activate

Make sure you pass the correct load option.

Use --load-builtin-plugins for built-in plugins, or --load-plugins for your own plugin packages. Both options can be repeated.

framex run --load-builtin-plugins echo
framex run --load-plugins my_plugin --load-plugins another_plugin

That means the hook reformatted files in CI.

Run the same formatter locally, commit the updated files, and push again:

pre-commit run --all-files

If the repo uses pre-commit.ci, the auto-fix only applies to writable pull request branches. It does not create a new pull request for you.

This usually means a third-party dependency does not ship type information.

There are two practical solutions.

This is not the recommended option, but it is acceptable when no stub package exists.

Add a targeted ignore rule in mypy.ini or pyproject.toml.

For example, for mindforge:

[mypy-mindforge.*]
ignore_missing_imports = True

Avoid disabling missing-import checks globally. Keep the ignore rule scoped to the specific dependency.

This is the recommended option when a matching type stub package exists.

For example:

uv add types-pytz --dev
uv add types-pyyaml --dev

Use this path for libraries such as:

If a stub package exists, prefer installing it over adding an ignore rule.