uvenv - workflow tool for uv.

The uvenv command is a wrapper around the uv command. It provides a simple interface for managing Python projects, inspired by tools like pipenv, but using requirements.txt and requirements.in files.

Note: This is an active work in progress. Some features may not be fully implemented, and are subject to change.

Project Structure

uvenv assumes the following project structure:

• requirements.in — A file containing the packages to be installed.
• requirements.txt — A lockfile containing the exact versions of the packages to be installed.
• .venv — A directory containing the virtual environment.

uvenv will automatically discover the project root by searching for these files in the current directory and its parents.

Environment Variables

uvenv allows you to customize the locations of key files and directories using environment variables:

• UVENV_REQUIREMENTS_IN: Specifies the location of the requirements input file (default: requirements.in)
• UVENV_REQUIREMENTS_TXT: Specifies the location of the requirements lockfile (default: requirements.txt)
• UVENV_VENV_DIR: Specifies the directory for the virtual environment (default: .venv)
• UVENV_UV: Specifies the path to the uv executable (default: uv)
• UVENV_PYTHON: Specifies the Python interpreter to use (default: python)

For example, to use a different name for your requirements file:

$ export UVENV_REQUIREMENTS_IN=requirements-dev.in
$ export UVENV_REQUIREMENTS_TXT=requirements-dev.txt
$ export UVENV_VENV_DIR=~/.venvs/myproject

$ uvenv install

Commands

uvenv currently provides the following primary commands:

• uvenv install — Install the packages in requirements.in.
• uvenv uninstall — Uninstall the packages in requirements.in.
• uvenv lock — Generate or update the lockfile in requirements.txt.

---

Philosophy

• Simplicity: uvenv aims to provide a simple and intuitive interface for managing Python projects.
• Speed: uvenv leverages the speed of uv for dependency management and virtual environment creation.
• Flexibility: uvenv aims to be flexible and support a variety of project structures and workflows.
• Compatibility: uvenv aims to be compatible with a variety of Python versions and platforms.
• Minimalism: uvenv aims to be minimal and avoid unnecessary complexity.
• Power: uvenv aims to provide powerful features for managing Python projects.
• Community: uvenv aims to be community-driven and open-source.

Features

• Automatic project root discovery
• Virtual environment management
• Dependency installation and uninstallation
• Requirements locking
• Command running within the virtual environment
• Interactive shell with activated virtual environment

Installation

To install uvenv, you need to have Python 3.6+ and uv installed. Then you can install uvenv using pip:

$ pip install uvenv-cli

Usage

uvenv provides the following commands:

Install

Install dependencies or specific packages:

$ uvenv install
$ uvenv install <package1> <package2>

Uninstall

Remove specific packages:

$ uvenv uninstall <package1> <package2>

Lock

Generate or update requirements.txt:

$ uvenv lock

Help

Show help message:

$ uvenv --help

Project Structure

uvenv expects your project to have either a requirements.txt or requirements.in file in the project root. It will automatically discover the project root by searching for these files in the current directory and its parents.

Usage

1. Start a new project:

   $ mkdir myproject
   $ cd myproject
   $ echo "requests==2.26.0" > requirements.in
   $ uvenv install
   

2. Add a new package:

   $ uvenv install numpy
   

3. Remove a package:

   $ uvenv uninstall requests
   

4. Update locked requirements:

   $ uvenv lock
   

Upcoming features

5. Run a Python script:

   $ uvenv run python myscript.py
   

6. Start an interactive shell:

   $ uvenv shell
   

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project will be licensed under the MIT License.