@@ -34,6 +34,36 @@ or to install all supported MLIPs::
3434 uv sync --all-extras
3535
3636
37+ Using uv
38+ ++++++++
39+
40+ ``uv `` manages a `persistent environment <https://docs.astral.sh/uv/concepts/projects/layout/#the-project-environment >`_
41+ with the project and its dependencies in a ``.venv `` directory, adjacent to ``pyproject.toml ``. This will be created automatically as needed.
42+
43+ ``uv `` provides two separate APIs for managing your Python project and environment.
44+
45+ ``uv pip `` is designed to resemble the ``pip `` CLI, with similar commands (``uv pip install ``, ``uv pip list ``, ``uv pip tree ``, etc.),
46+ and is slightly lower level. `Compared with pip <https://docs.astral.sh/uv/pip/compatibility/ >`_,
47+ ``uv `` tends to be stricter, but in most cases ``uv pip `` could be used in place of ``pip ``.
48+
49+ ``uv add ``, ``uv run ``, ``uv sync ``, and ``uv lock `` are known as "project APIs", and are slightly higher level.
50+ These commands interact with (and require) ``pyproject.toml ``, and ``uv `` will ensure your environment is in-sync when they are called,
51+ including creating or updating a `lockfile <https://docs.astral.sh/uv/concepts/projects/sync/ >`_,
52+ a universal resolution that is `portable across platforms <https://docs.astral.sh/uv/concepts/resolution/#universal-resolution >`_.
53+
54+ When developing for ``janus-core ``, it is usually recommended to use project commands, as described in `Getting started `_
55+ rather than using ``uv pip install `` to modify the project environment manually.
56+
57+ .. tip ::
58+
59+ ``uv `` will detect and use Python versions available on your system,
60+ but can also be used to `install Python automtically <https://docs.astral.sh/uv/guides/install-python/ >`_.
61+ The desired Python version can be specified when running project commands with the ``--python ``/``-p `` option.
62+
63+
64+ For further information, please refer to the `documentation <https://docs.astral.sh/uv/ >`_
65+
66+
3767Running unit tests
3868++++++++++++++++++
3969
0 commit comments