Skip to content

Commit 85d5807

Browse files
Add uv description (#396)
1 parent eb2a837 commit 85d5807

File tree

1 file changed

+30
-0
lines changed

1 file changed

+30
-0
lines changed

docs/source/developer_guide/get_started.rst

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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+
3767
Running unit tests
3868
++++++++++++++++++
3969

0 commit comments

Comments
 (0)