uv-tool

Run a command from a package, without installing it

$ uv tool run [command]

$ uv tool install [package]

$ uv tool upgrade [package]

$ uv tool uninstall [package]

$ uv tool list

uvtool <command> [options]

Common commands include: create, destroy, list, info, update-images.

create
    Create a new virtual machine.

-c <cpu_count>
    Number of virtual CPUs for the VM (e.g., 2).

-d <disk_size>
    Disk size for the VM (e.g., 8G for 8 gigabytes).

-m <memory_size>
    Memory size for the VM (e.g., 1024M for 1 gigabyte).

-i <image_name>
    Specify the Ubuntu cloud image to use (e.g., xenial, focal). Use update-images to see available options.

-n <vm_name>
    A unique name to identify the new virtual machine.

--ssh-public-key-file <path>
    Path to an SSH public key file to inject into the VM for root access.

--cloud-config-file <path>
    Path to a cloud-config YAML file for advanced VM customization.

destroy <vm_name>
    Destroy (delete) a specified virtual machine.

list
    List all virtual machines managed by uvtool.

--active
    Used with list to show only running VMs.

--inactive
    Used with list to show only stopped VMs.

info <vm_name>
    Display detailed information about a specific virtual machine.

update-images
    Update the local cache of available Ubuntu cloud images from remote repositories.

uvtool is a command-line utility designed to simplify the management of Ubuntu cloud images within a libvirt virtualization environment. It provides a higher-level abstraction over direct virsh commands, making it easier for developers and testers to create, destroy, list, and modify virtual machines based on official Ubuntu cloud images.

It automatically handles the downloading and caching of Ubuntu cloud images, allowing users to quickly provision new VMs. Furthermore, uvtool integrates seamlessly with cloud-init, enabling the automatic injection of SSH keys, user data, and other initial configuration upon VM startup. This tool is particularly useful for quickly spinning up ephemeral Ubuntu environments for development, testing, or demonstration purposes without needing to delve into the complexities of raw libvirt commands.

uvtool relies on libvirt being installed and properly configured on the host system. It is specifically designed for Ubuntu cloud images and may not function as expected with other operating system images. Network access is required for initial image downloads. While powerful for single VM management, it is not a full-fledged orchestration tool for complex multi-VM setups.

uvtool leverages cloud-init, a standard multi-distribution package that handles early initialization of a cloud instance. This allows users to pass configuration data (like SSH keys, user accounts, and bootstrap scripts) directly to the VM during its first boot, enabling highly automated and customizable deployments.

To speed up VM creation, uvtool maintains a local cache of downloaded Ubuntu cloud images. When you request a VM using an image, uvtool first checks its cache. If the image is not present or an update is available (and update-images has been run), it downloads the necessary image, reducing subsequent provisioning times.

uvtool was developed by Canonical, the company behind Ubuntu, to streamline the process of creating and managing virtual machines from Ubuntu cloud images. Its inception aimed to provide a simpler command-line interface for common VM provisioning tasks, thereby reducing the complexity of direct interaction with libvirt APIs. It fills a niche for developers and testers who frequently need to spin up and tear down clean Ubuntu environments for isolated testing or development work.

virsh(1), qemu-kvm(1), multipass(1), lxc(1)