Metadata-Version: 2.5
Name: USB-Imager
Version: 4.1.2
Summary: GUI-Application to write disk images to USB keys
Keywords: boot,dd,flash,image,img,iso,usb,write,writer
Author-email: Secu-Design® <development@secu-design.com>
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Utilities
License-File: LICENSE
Requires-Dist: PySide6-Essentials>=6.4
Requires-Dist: jeepney>=0.9,<1.0
Project-URL: Changelog, https://gitlab.com/secu-design/usb-imager/-/blob/master/CHANGELOG.md
Project-URL: Donate, https://buymeacoffee.com/secudesign
Project-URL: Homepage, https://gitlab.com/secu-design/usb-imager
Project-URL: Issues, https://gitlab.com/secu-design/usb-imager/-/issues
Project-URL: Source, https://gitlab.com/secu-design/usb-imager
Import-Name: usbimager

USB-Imager
==========

`USB-Imager`_ is a GUI application for Linux to write disk images to multiple USB drives at once.

.. image:: https://img.shields.io/pypi/v/usb-imager
   :target: https://pypi.org/project/usb-imager
   :alt: PyPI version

.. image:: https://img.shields.io/pypi/pyversions/usb-imager
   :target: https://pypi.org/project/usb-imager
   :alt: Supported Python versions

.. image:: https://img.shields.io/pypi/l/usb-imager
   :target: https://www.gnu.org/licenses/gpl-3.0-standalone.html
   :alt: License: GPLv3+

.. image:: https://gitlab.com/secu-design/usb-imager/badges/master/pipeline.svg
   :target: https://gitlab.com/secu-design/usb-imager/-/pipelines
   :alt: Pipeline status

.. image:: https://img.shields.io/pypi/dm/usb-imager
   :target: https://pypi.org/project/usb-imager
   :alt: Monthly downloads

.. image:: https://img.shields.io/badge/Buy_Me_A_Coffee-support-FFDD00?logo=buymeacoffee&logoColor=black
   :target: https://buymeacoffee.com/secudesign
   :alt: Buy Me A Coffee

:License:
   `GPLv3+`_
:Copyright:
   © 2021-2026 by Secu-Design®
:Donation:
   `Buy Me A Coffee`_


.. image:: https://gitlab.com/secu-design/usb-imager/-/raw/4.1.2/screenshots/screenshot_main.png
   :target: https://gitlab.com/secu-design/usb-imager/-/blob/4.1.2/screenshots/screenshot_main.png
   :alt: USB-Imager screenshot
   :width: 630px


1. Requirements
---------------

* Linux with a running **udisks2** service, version 2.7.3 or newer
* Python ≥ 3.10
* `PySide6-Essentials`_ ≥ 6.4
* `jeepney`_ ≥ 0.9

USB-Imager itself does not run as root. Device access is handled by
udisks2, which authorizes writing via polkit. Depending on your
distribution's policy, you may be prompted for a password.


2. Features
-----------

* Writing an image to multiple USB sticks at once
* Automatic device detection
* Very fast writing by using the linux system call ``sendfile()`` and large write buffers
* Adjustable write buffer between 1 MiB and 4 MiB
* Optional validation after writing
* Optional checksum verification of the selected image
* Detection and elimination of the following states of a device before writing:

  - Mounted

* Shows a warning if an ISO file does not look bootable
* Shows stats about writing time and overall speed
* Selectable color schemes (Dark/Light Mode)

Planned:

* Deactivation of LVM2 volumes before writing
* Multilanguage support


3. Installation
---------------

**Flatpak:**

The `Flatpak`_ package is the only installation that integrates USB-Imager into your desktop. It adds an entry to
the application menu, so no terminal is needed to start it.

.. code:: bash

  $ flatpak install flathub io.gitlab.secu_design.usb-imager
  $ flatpak run io.gitlab.secu_design.usb-imager
  $ flatpak uninstall io.gitlab.secu_design.usb-imager

**Virtual environment:**

An installation in a virtual environment allows starting USB-Imager only from a terminal. If the command
``usb-imager`` is not available there, read section `5. Troubleshooting`_.

`pipx`_:

.. code:: bash

  $ pipx install usb-imager
  $ usb-imager
  $ pipx uninstall usb-imager

`pipenv`_:

.. code:: bash

  $ pipenv install usb-imager
  $ pipenv run usb-imager
  $ pipenv uninstall usb-imager

`venv`_:

.. code:: bash

  $ python3 -m venv venv
  $ source venv/bin/activate
  $ pip install usb-imager
  $ usb-imager
  $ pip uninstall usb-imager
  $ deactivate
  $ rm -rf venv


4. Usage
--------

Installed as a Flatpak, USB-Imager is started from the application menu of your desktop, like any other
application.

After an installation into a virtual environment, type ``usb-imager`` in your terminal window. Such an
installation puts its data files into the environment, where no menu indexer looks for them, so it offers no
desktop entry.


5. Troubleshooting
------------------

5.1. Command ``usb-imager`` not found
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On some Linux distributions USB-Imager cannot be started from the command line when it was installed into
``~/.local``, as ``pipx`` does. ``~/.local/bin`` is not part of the executable search path on every system. Add the
directory to the search path of your shell, then open a new terminal.

Bash, Zsh and other POSIX shells, in ``~/.profile``:

.. code:: bash

  PATH=~/.local/bin:$PATH

Fish:

.. code:: bash

  $ fish_add_path ~/.local/bin

5.2. Qt platform plugin ``xcb`` cannot be loaded
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On some Linux distributions, starting USB-Imager after a ``pipx``, ``pipenv`` or ``venv`` installation fails with
an error mentioning ``xcb-cursor0`` or ``libxcb-cursor0``. This system library is required by Qt since version
6.5 but is missing on some systems. Install it through your distribution's package manager, for example on
Debian, Ubuntu and Linux Mint:

.. code:: bash

  $ sudo apt install libxcb-cursor0


6. Support
----------

| If you want to report a bug or request a feature, you can do so `here`_.
| You can also write an email to `Secu-Design® | Development`_.


7. Donate
---------

If you like USB-Imager and want to support its development, you can `buy me a coffee`_.


.. _USB-Imager: https://pypi.org/project/usb-imager
.. _GPLv3+: https://www.gnu.org/licenses/gpl-3.0-standalone.html
.. _Secu-Design® | Development: mailto:development@secu-design.com

.. _PySide6-Essentials: https://pypi.org/project/PySide6-Essentials/
.. _jeepney: https://pypi.org/project/jeepney/

.. _Flatpak: https://flathub.org/apps/io.gitlab.secu_design.usb-imager
.. _pipx: https://pipx.pypa.io/stable/
.. _pipenv: https://pipenv.pypa.io/en/latest/
.. _venv: https://docs.python.org/3/library/venv.html

.. _here: https://gitlab.com/secu-design/usb-imager/issues
.. _buy me a coffee: https://buymeacoffee.com/secudesign

