{"id":13510831,"url":"https://github.com/virt-lightning/virt-lightning","last_synced_at":"2026-02-19T23:01:10.007Z","repository":{"id":37458196,"uuid":"169650122","full_name":"virt-lightning/virt-lightning","owner":"virt-lightning","description":"Starts your VM on libvirt in a couple of seconds!","archived":false,"fork":false,"pushed_at":"2026-02-05T18:49:30.000Z","size":763,"stargazers_count":237,"open_issues_count":16,"forks_count":49,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-02-06T04:31:24.738Z","etag":null,"topics":["cloud-image","cloud-images","cloud-init","guestfs","kvm","kvm-hypervisor","libvirt"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/virt-lightning.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE-2.0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-02-07T22:06:14.000Z","updated_at":"2026-02-05T18:50:10.000Z","dependencies_parsed_at":"2023-01-21T07:16:13.839Z","dependency_job_id":"32fcf598-80f8-44b8-bf05-6fef24c32f8d","html_url":"https://github.com/virt-lightning/virt-lightning","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/virt-lightning/virt-lightning","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virt-lightning%2Fvirt-lightning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virt-lightning%2Fvirt-lightning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virt-lightning%2Fvirt-lightning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virt-lightning%2Fvirt-lightning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/virt-lightning","download_url":"https://codeload.github.com/virt-lightning/virt-lightning/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virt-lightning%2Fvirt-lightning/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29636035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"ssl_error","status_checked_at":"2026-02-19T22:32:38.330Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-image","cloud-images","cloud-init","guestfs","kvm","kvm-hypervisor","libvirt"],"created_at":"2024-08-01T02:01:55.837Z","updated_at":"2026-02-19T23:01:09.990Z","avatar_url":"https://github.com/virt-lightning.png","language":"Python","readme":"# 🗲 spawn Cloud instances on libvirt!🗲\n\n\n[![PyPI version](https://badge.fury.io/py/virt-lightning.svg)](https://badge.fury.io/py/virt-lightning)\n[![Documentation](https://shields.io/static/v1?message=Documentation\u0026color=blue)](https://virt-lightning.org/)\n\n![Logo](./logo/logo_no_text.png)\n\nYou want to spawn local VM quickly.. Like... really quickly. You want them to be as generic as possible. Actually you would like to reuse some existing cloud images!\n\nThis is the right tool for you.\n\nVirt-Lightning exposes a CLI inspired by the Cloud and Vagrant.\nIt can also prepare the Ansible inventory file.\n\nThis is handy to quickly validate a new Ansible playbook, or a role on a large number of environments.\n\n### example: less than 30 seconds to spawn an instance ⚡\n\nIn a nutshell:\n\n```shell\necho \"- distro: centos-7\" \u003e virt-lightning.yaml\nvl up\nvl ansible_inventory \u003e inventory\nansible all -m ping -i inventory\n```\n\n### example: or 75 seconds for 10 nodes lab ⚡\n\nDuring this recording, we:\n\n1. use the list of distributions to generate a virt-lightning.yaml file.\n2. we then create an environment based on this file\n3. once the environment is ready, we generate an Ansible inventory file\n4. and we use it to call Ansible's ping module on all the host.\n\n[![demo](https://asciinema.org/a/230671.svg)](https://asciinema.org/a/230671?autoplay=1)\n\n\n## Requirements\n- Python 3.8 or greater\n- The Python3 binding for libvirt, the package is probably called `python3-libvirt` or `libvirt-python` according to pip.\n- Libvirt must be running, most of the time you just need to run: `sudo systemctl start --now libvirtd`\n- Finally, be sure your user can access the system libvirt daemon, e.g with: `virsh -c qemu:///system`\n\n## Optional\n- You make also want to install `python3-urwid` if you want to get the fancy list of VMs. This dependency is optional.\n\n\n## Installation (Fedora/RHEL)\n\n```shell\nsudo dnf install uv python3-libvirt libvirt-devel gcc python3-devel\nuvx virt-lightning\n```\n\n## Installation (Fedora Atomic, e.g Silverblue)\n\nVirt-Lightning won't work from toolbox or a container.\n\n\n``` shell\nrpm-ostree install genisoimage libvirt libvirt-client libvirt-daemon-kvm python3-libvirt\nsystemctl reboot\n(...)\nsudo systemctl enable --now libvirtd\nsudo systemctl enable --now virtqemud.socket\nsudo systemctl enable --now virtnetworkd.socket\nsudo systemctl enable --now virtstoraged.socket\n\n# You can also layer pipx\npython3 -m venv venv --system-site-packages\n./venv/bin/pip install virt-lightning\n./venv/bin/vl\n```\n\n## Installation (Debian/Ubuntu)\n\n```shell\nsudo apt install python3-venv pkg-config gcc libvirt-dev python3-dev pipx\npipx ensurepath\npipx install virt-lightning\n```\n\n## Post Installation\n\n`virt-lightning` will be installed in ~/.local/bin/. Add it in your `$PATH` if\nit's not already the case. For instance you can use:\n\n```shell\necho \"export PATH=$PATH:~/.local/bin/\" \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n# List Remote Images\n\nBefore you start your first VM, you need to list the images. To do so,\nyou just use the `vl remote_images` command:\n\n```shell\n$ vl remote_images\n```\n\n# Fetch some images\n\nBefore you start your first VM, you need to fetch the images. To do so,\nyou just use the `vl pull` command:\n\n```shell\n$ vl pull fedora-32\n```\n\nYou can also pull an image from Internet, as soon as it's a `.qcow2` or a `.qcow2.xz` (compress with `xz`):\n\n```shell\n$ vl pull freebsd-16-current --url https://download.freebsd.org/snapshots/VM-IMAGES/16.0-CURRENT/amd64/Latest/FreeBSD-16.0-CURRENT-amd64-BASIC-CLOUDINIT-ufs.qcow2.xz\n```\n\n# Actions\n\n`vl` is an alias for `virt-lightning`, you can use both. In the rest of the document\nwe use the shortest version.\n\n## **vl images**\n\nList the distro images that can be used. Its output is compatible with `vl up`. You can initialize a new configuration with: `vl images \u003e virt-lightning.yaml`.\n\n## **vl up**\n\n`virt-lightning` will read the `virt-lightning.yaml` file from the current directory and prepare the associated VM.\n\n## **vl down**\n\nDestroy all the VMs managed by Virt-Lightning.\n\n## **vl start**\n\nStart a specific VM, without reading the `virt-lightning.yaml` file.\n\n## **vl stop**\n\nStop just one VM.\n\n## **vl status**\n\nList the VMs, their IP and if they are reachable.\n\n## **vl ansible_inventory**\n\nExport an inventory in the Ansible format.\n\n**Note:** Created VMs use various Python versions, which can cause compatibility issues with the Ansible version on the control node (host). In case of errors related to Python version compatibility, please consult the Ansible [changelog](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html) for details on supported Python versions.\n\nIn can you need a different Python version for a given image (`ansible_python_interpreter`), you can define it in a YAML file aside of the qcow2 image. E.g:\n\n```\n$ ls -l /var/lib/virt-lightning/pool/upstream/netbsd-10.0.qcow2\n-rw-r--r--. 1 qemu qemu 242483200 Nov  5 18:50 /var/lib/virt-lightning/pool/upstream/netbsd-10.0.qcow2\n$ cat /var/lib/virt-lightning/pool/upstream/netbsd-10.0.yaml\npython_interpreter: /usr/pkg/bin/python3.12\n\n```\n\n## **vl ssh**\n\nShow up a menu to select a host and open a ssh connection.\n\n[![vl ssh](https://asciinema.org/a/230675.svg)](https://asciinema.org/a/230675?autoplay=1)\n\n## **vl console**\n\nLike `vl ssh` but with the serial console of the VM.\n\n[![vl ssh](https://asciinema.org/a/230677.svg)](https://asciinema.org/a/230677?autoplay=1)\n\n\n## **vl viewer**\n\nLike `vl console` but with the SPICE console of the VM. Requires `virt-viewer`.\n\n## **vl pull**\n\nDownload a VM image. Use the `vl remote_images` to get a list of available images. You can also update the custom configuration to add a private image hub.\n\n# Configuration\n\n## Global configuration\n\nIf `~/.config/virt-lightning/config.ini` exists, Virt-Lightning will read\nits configuration there.\n\n```ini\n[main]\nnetwork_name = virt-lightning\nroot_password = root\nstorage_pool = virt-lightning\nnetwork_auto_clean_up = True\nssh_key_file = ~/.ssh/id_rsa.pub\n```\n\n**network_name**: if you want to use an alternative libvirt network\n\n**root_password**: the root password\n\n**storage_pool**: if you want to use an alternative libvirt storage pool\n\n**network_auto_clean_up**: if you want to automatically remove a network when running `virt-lightning down`\n\n**ssh_key_file**: the path of the default public key for connecting to VMs. If unset, Virt-Lightning will pick the first key matching `~/.ssh/id_*.pub` or (if none found) all keys from `ssh-add -L`.\n\n**private_hub**: if you need to set additional url from where images should be retrieved, update the configuration file `~/.config/virt-lightning/config.ini` adding the following\n```\n[main]\nprivate_hub=url1,url2\n```\n\n**custom_image_list**: if you wish to use a custom image list, update the configuration file `~/.config/virt-lightning/config.ini` adding the following\n```\n[main]\ncustom_image_url=\u003curl\u003e/images.json\n```\ntake a look at [images.json](virt-lightning.org/images.json) for a reference\n\n## VM configuration keys\n\nA VM can be tuned at two different places with the following keys:\n\n- `distro`: the name of the base distro image to use, it's the only mandatory parameter.\n- `name`: the VM name\n- `memory`: the amount of memory to dedicate to the VM\n- `vcpus`: the number of vcpu to dedicate to the VM\n- `root_password`: the root password in clear text\n- `ssh_key_file`: the path of the public key for connecting to the VM. If unset, and no global default present, Virt-Lightning will pick the first key matching `~/.ssh/id_*.pub` or (if none found) all keys from `ssh-add -L`.\n- `groups`: this list of groups will be used if you generate an Ansible inventory.\n- `disks`: a list of disks to create and attach to the VM. The first one is used as the root disk. Default to `[{\"size\": 15}]`\n    - `size` the size of the disk in GB. Default is `1`.\n- `networks`: a list of network to attach to the VM. The default is: one virtio interface attached to `virt-lightning` network.\n    - `network`: the name of the libvirt network. Default is the key `network_name` from the configuration (`virt-lightning` by default). The key cannot be used with `bridge`. A host variable is added to in the Ansible inventory, with the network name with suffix \"_ipv4\" as key and the IPv4 as value, e.g. \"private_ipv4\".\n    - `ipv4`: a static IPv4. Default is a dynamic IPv4 address.\n    - `nic_model`: the libvirt driver to use. Default is `virtio`\n    - `mac`: an optional static MAC address, e.g: '52:54:00:71:b1:b6'\n    - `bridge`: optional, the name of a bridge to connect to. This key replace the `network` key.\n    - `virtualport_type`: The type of the virtualport, currently, this can be used with `bridge`.\n\n### Example: a `virt-lightning.yaml` file:\n\n```yaml\n- name: esxi-vcenter\n  distro: esxi-6.7\n  memory: 12000\n  root_disk_size: 30\n  vcpus: 2\n  root_password: '!234AaAa56'\n  groups: ['all_esxi']\n- name: esxi1\n  distro: esxi-6.7\n  memory: 4096\n  vcpus: 1\n  root_password: '!234AaAa56'\n  groups: ['all_esxi', 'esxi_lab']\n- name: esxi2\n  distro: esxi-6.7\n  memory: 4096\n  vcpus: 1\n  root_password: '!234AaAa56'\n  groups: ['all_esxi', 'esxi_lab']\n- name: centos-7\n  distro: centos-7\n  networks:\n    - network: default\n      ipv4: 192.168.122.50\n  bootcmd:\n    - yum update -y\n```\n\n### Example: connect to an OpenvSwitch bridge\n\n```yaml\n- name: controller\n  distro: fedora-35\n  - bridge: my-ovs-bridge-name\n    virtualport_type: openvswitch\n```\n\n### Example: To getting DHCP working with a bridge connection\n\n```yaml\n- name: vlvm-fedora-40\n  distro: fedora-40\n  networks:\n    - network: virt-lightning\n      nic_model: virtio\n    - bridge: br0\n      nic_model: virtio\n```\n\n### Example: Addressing multiple interfaces\n```yaml\n- name: example\n  distro: fedora-40\n  networks:\n    - network: default\n      ipv4: 192.168.122.50\n    - network: management\n      ipv4: 192.168.123.50\n```\n\nThe variable `management_ipv4` holds the IP address and netmask.\n```yaml\n- hosts: all\n  tasks:\n    - name: Default address\n      debug: msg=\"{{ ansible_host }}\"\n      # \"msg\": \"192.168.122.50\"\n    - name: Management address\n      debug: msg=\"{{ management_ipv4 }}\"\n      # \"msg\": \"192.168.123.50/24\"\n    - name: Management address\n      debug: msg=\"{{ management_ipv4 | ansible.utils.ipaddr('address') }}\"\n      # \"msg\": \"192.168.123.50\"\n    - name: Management address\n      debug: msg=\"{{ management_ipv4 | ansible.utils.ipaddr('netmask') }}\"\n      # \"msg\": \"255.255.255.0\"\n```\n\n### You can also associate some parameters to the distro image itself\n\n```shell\ncat /var/lib/virt-lightning/pool/upstream/esxi-6.7.yaml\nusername: root\npython_interpreter: /bin/python\nmemory: 4096\nnetworks:\n  - network: virt-lightning\n    nic_model: virtio\n  - network: default\n    nic_model: e1000\n```\n\n### Example: working with snapshots\n\nUser can create a snapshot of VM to restore it later. Default configuration of `virt-lightning` supports snapshots both\nfor running and powering off VMs. `qcow2` disk format used allows diskspace-wise incremental snapshotting, keeping only\nupdated storage blocks. `virsh` tool supports it by CLI, `virt-manager` provides a neat GUI supporting most of\nthe features\n```shell\n# create first snapshot of running machine\nvirsh snapshot-create-as --domain vm_name --name snapshot_1\n# create second snapshot\nvirsh snapshot-create-as --domain vm_name --name snapshot_2\n# validate that both of them were saved\nvirsh snapshot-list vm_name\n# and revert to the first one\nvirsh snapshot-revert vm_name --snapshotname snapshot_1\n```\n\n### Development\n\ninstall libvirt-dev package:\n\nDebian/Ubuntu:\n```shell\napt install python3-venv pkg-config gcc libvirt-dev python3-dev\n```\n\nFedora/RHEL:\n```shell\ndnf install python3-devel gcc libvirt-devel\n```\n\nYou can run a development copy in a virtual env:\n```shell\nuv run virt-lightning\n```\n\n### Add a new image or refresh the list\n\nYou just need to adjust the `virt-lightning.org/refresh.py` script and call it with:\n\n```shell\nuv run virt-lightning.org/refresh.py\n```\n","funding_links":[],"categories":["Python","others"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirt-lightning%2Fvirt-lightning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvirt-lightning%2Fvirt-lightning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirt-lightning%2Fvirt-lightning/lists"}