# Installing and using Cylc with uv

**URL:** <https://cylc.discourse.group/t/installing-and-using-cylc-with-uv/1155>\
**Category:** Cylc Support\
**Created:** [April 22, 2025, 6:17pm UTC](https://cylc.discourse.group/t/installing-and-using-cylc-with-uv/1155 "2025-04-22T18:17:29Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![blaylockbk](https://yyz2.discourse-cdn.com/free1/user_avatar/cylc.discourse.group/blaylockbk/32/157_2.png) [@blaylockbk](https://cylc.discourse.group/u/blaylockbk)\
**Post date:** [April 22, 2025, 6:17pm UTC](https://cylc.discourse.group/t/installing-and-using-cylc-with-uv/1155/1 "2025-04-22T18:17:29Z")

</div>

Hi all,

I just installed Cylc 8 with [uv](https://docs.astral.sh/uv/). It installed _very_ quickly (~10 seconds). I wondered if anyone else has used uv to manage a Cylc project and if they ran into any hiccups. I can’t seem to get the gui to work.

My steps:

1. [Installed uv](https://docs.astral.sh/uv/#installation).

2. Created a new project.  
Since the gui only works with Python 3.9 at the moment, I pinned that version…

3. Added cylc-flow and cylc-uiserver as dependencies

* * *

While in my project directory, I can run the Cylc command in the venv like this:

```bash
uv run cylc

```

Doing `uv run cylc --version` gives me `8.4.2`.

I can also invoke the tui

```bash
uv run cylc tui

```

* * *

But when I try using the gui with `uv run cylc gui` I get this error:

```auto
"cylc gui" requires "cylc-uiserver"

ModuleNotFoundError: No module named 'pkg_resources'

```

This is strange to me because I have installed cylc-uiserver in the venv. When I do `uv pip list` I see that I have the dependency is installed in the venv…

```auto
...
cylc-flow 8.4.2
cylc-uiserver 1.6.1
...

```

I also have `node` and `npm` in my path. Maybe I’m still missing something.

* * *

I think its neat that I can also use Cylc as a uv tool (without installing it in a venv), but I don’t know how this behaves when actually running workflows.

```auto
uvx --from cylc-flow cylc

```

```auto
uvx --from cylc-flow cylc tui

```

---

<div class="post-metadata">

**Author:** ![hilary.j.oliver](https://yyz2.discourse-cdn.com/free1/user_avatar/cylc.discourse.group/hilary.j.oliver/32/4_2.png) [@hilary.j.oliver](https://cylc.discourse.group/u/hilary.j.oliver)\
**Post date:** [April 22, 2025, 11:17pm UTC](https://cylc.discourse.group/t/installing-and-using-cylc-with-uv/1155/2 "2025-04-22T23:17:55Z")

</div>

Hi @blaylockbk

Huh, yeah `uv` seems great, I just tried it myself. I like the project directory style (although we might need to think about how to use it with the Cylc multi-version wrapper).

> [@blaylockbk](#):
>
> ```auto
> "cylc gui" requires "cylc-uiserver"
> 
> ModuleNotFoundError: No module named 'pkg_resources'
> 
> ```

Missing `pkg_resources` seems to be the root cause of that. I did this in the project:

```auto
$ uv add setuptools
$ uv run cylc gui

```

and everything worked perfectly (GUI, a running workflow, and some intervention commands - `cylc trigger` etc.).

---

<div class="post-metadata">

**Author:** ![oliver.sanders](https://yyz2.discourse-cdn.com/free1/user_avatar/cylc.discourse.group/oliver.sanders/32/110_2.png) [@oliver.sanders](https://cylc.discourse.group/u/oliver.sanders)\
**Post date:** [April 23, 2025, 8:35am UTC](https://cylc.discourse.group/t/installing-and-using-cylc-with-uv/1155/3 "2025-04-23T08:35:39Z")

</div>

I’ve switched from `pip` to `uv pip` with no problems, but would generally recommend installing from conda-forge (e.g. using `conda`, `mamba` or `pixi`) rather than from pypi (e.g. using `pip` or `uv`) because this ensures the full stack is installed (including system tools that are not available on pypi).

`uvx`, `pipx` and other similar tools are a good way to install many CLI tools, they install packages into virtual environments behind the scenes and expose their commands using wrapper scripts. This is much the same as our recommended deployment pattern (see [Installation — Cylc 8.4.2 documentation](https://cylc.github.io/cylc-doc/stable/html/installation.html#managing-environments)), however, it does not support the installation of parallel Cylc environments (e.g. we have multiple versions of Cylc installed at the same time).

These venv + wrapper script solutions should work fine with Cylc. However, Cylc is not a simple fire-and-forget CLI tool, it’s a full distributed system that needs to launch subprocesses and invoke itself over SSH, so there may be complications.

> ModuleNotFoundError: No module named ‘pkg\_resources’

Makes sense, this dependency will be removed in the next cylc-uiserver release.

---

<div class="post-metadata">

**Author:** ![blaylockbk](https://yyz2.discourse-cdn.com/free1/user_avatar/cylc.discourse.group/blaylockbk/32/157_2.png) [@blaylockbk](https://cylc.discourse.group/u/blaylockbk)\
**Post date:** [April 28, 2025, 3:56pm UTC](https://cylc.discourse.group/t/installing-and-using-cylc-with-uv/1155/4 "2025-04-28T15:56:49Z")

</div>

Thanks! Adding setuptools worked!

---

<div class="post-metadata">

**Author:** ![blaylockbk](https://yyz2.discourse-cdn.com/free1/user_avatar/cylc.discourse.group/blaylockbk/32/157_2.png) [@blaylockbk](https://cylc.discourse.group/u/blaylockbk)\
**Post date:** [April 28, 2025, 4:05pm UTC](https://cylc.discourse.group/t/installing-and-using-cylc-with-uv/1155/5 "2025-04-28T16:05:05Z")

</div>

Thanks @oliver.sanders for your thoughts.