install-locked-env

A minimalist CLI tool easing the local installation of "locked environments" described in lock files available in repositories on the web.

Installation

The simplest way to install and run install-locked-env is by using the UV command uvx:

uvx install-locked-env <url>

Of course, install-locked-env can also be installed with uv tool, pipx or even pip. For example, to install globally with UV, run:

uv tool install install-locked-env

Alternatively, the conda-forge package can be installed with:

pixi global install install-locked-env

Usage

Basic Usage

Install a locked environment from a web source:

install-locked-env https://github.com/fluiddyn/fluidsim/tree/branch/default/pixi-envs/env-fluidsim

If Pixi is installed, this should give something like this

✓ Detected github repository
  Repository: fluiddyn/fluidsim
  Path: pixi-envs/env-fluidsim
✓ Saved files to /home/myusername/env-fluidsim
  Environment type: pixi
  log file installation: env-fluidsim/log_install.txt
✓ Installed environment: env-fluidsim
✓ Registered Jupyter kernel

Installation complete!
Activate with: pixi shell --manifest-path env-fluidsim

Different lock file formats (pylock.toml, uv.lock, pdm.lock, pixi.lock, ...) produced by different tools (UV, PDM, Pixi, ...) are supported.

⚠️ Caution

Use only with trusted repositories and lock files! install-locked-env potentially executes code in the installed environment.

Options

install-locked-env [OPTIONS] URL

╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --output              -o      PATH  Output directory (default: auto-generated)       │
│ --no-install                        Download files only, don't install               │
│ --no-register-kernel                Don't register Jupyter kernel if ipykernel is    │
│                                     present                                          │
│ --version                                                                            │
│ --minimal                           Only download the files necessary to create the  │
│                                     environment                                      │
│ --clone                             Clone the repo (only for repository url)         │
│ --download-method     -d      TEXT  Download method (default: auto): can be          │
│                                     'archive', 'file-per-file' or 'clone'            │
│ --install-completion                Install completion for the current shell.        │
│ --show-completion                   Show completion for the current shell, to copy   │
│                                     it or customize the installation.                │
│ --help                -h            Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────────────╯

Examples

Install from a repository URL:

Lockfile located in the root directory of a repository:

install-locked-env https://foss.heptapod.net/py-edu-fr/py-edu-fr

GitHub, GitLab and Heptapod are supported.

Install from a reference/directory URL:

install-locked-env https://github.com/fluiddyn/fluidsim/tree/branch/default/pixi-envs/env-fluidsim

or, with a precise commit reference:

install-locked-env https://github.com/fluiddyn/fluidsim/tree/5266c974e3368d17819f59b0e700b723591e0d1a/pixi-envs/env-fluidsim-mpi

For GitLab and Heptapod, the URLs have this format:

install-locked-env https://gitlab.com/user/project/-/tree/branch-name/envs/dev

For example:

install-locked-env https://foss.heptapod.net/fluiddyn/fluidsim/-/tree/branch/default/pixi-envs/env-fluidsim

It should be possible (not yet implemented) to give a lock file address (something like https://github.com/fluiddyn/fluidsim/tree/branch/default/pylock.toml).

Download only (no installation):

install-locked-env --no-install --output ./my-env https://github.com/user/repo

Skip Jupyter kernel registration:

install-locked-env --no-register-kernel https://github.com/user/repo

Supported Environment Types

Current (v0.2.0)

• ✅ Pixi (pixi.toml, pixi.lock)
• ✅ uv (pyproject.toml, uv.lock/pylock.toml)
• ✅ PDM (pyproject.toml, pdm.lock/pylock.toml)

Planned

• ⏳ Poetry (pyproject.toml, poetry.lock)

How it works

1. URL parsing: Extracts repository information (platform, owner, repo, ref, path)
2. File detection: Attempts to download supported lock files
3. Environment type detection: Determines the type based on downloaded files
4. Installation: Creates output directory and runs the appropriate installer
5. Jupyter registration: If ipykernel is present, registers the environment as a Jupyter kernel

Requirements

• Python 3.11+
• Pixi (for Pixi environments)
• UV (for uv.lock and pylock.toml)
• PDM (for pdm.lock)

Contributing

Contributions are welcome! See our contributing guide.

License

BSD-3-Clause