Metadata-Version: 2.4
Name: USB-Imager
Version: 3.1.0
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>=6.4
Requires-Dist: PyGObject>=3.42
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

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/3.1.0/Screenshot.png
   :target: https://gitlab.com/secu-design/usb-imager/-/blob/3.1.0/Screenshot.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`_ ≥ 6.4
* `PyGObject`_ ≥ 3.42
* The udisks2 introspection typelib (``gir1.2-udisks-2.0`` on Debian,
  ``typelib-1_0-UDisks-2_0`` on openSUSE)

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.

PyGObject is built from source during installation and needs its build
dependencies present (a C compiler, pkg-config and the development
headers for GObject introspection and cairo). See the `PyGObject
installation guide`_ for the packages your distribution requires.


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
* Flatpak support


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

**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
--------

Type ``usb-imager`` in your terminal window to start USB-Imager. A start via a desktop icon will only be
supported by the planned Flatpak package.


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

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


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: https://pypi.org/project/PySide6/
.. _PyGObject: https://pypi.org/project/PyGObject/
.. _PyGObject installation guide: https://pygobject.gnome.org/getting_started.html

.. _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

