# PyInstaller plugin for Poetry
Easily create executable binaries from your `pyproject.toml` using [PyInstaller](https://pyinstaller.org).
## Features
* **Multiple distribution formats**
* **Single file** created in `dist` folder (executable archive)
* **Folder** created in `dist` folder (containing executable and libraries)
* **Bundled** executable in platform specific wheels as scripts
* Both single file & folder distribution type can be bundled in wheels
## Installation
To install `poetry-pyinstaller-plugin` run the following command:
```shell
poetry self add poetry-pyinstaller-plugin
```
If you are having troubles to install the plugin please refer to Poetry documentation: https://python-poetry.org/docs/plugins/#using-plugins
## Configuration
Are listed in this sections all options available to configure `poetry-pyinstaller-plugin` in your `pyproject.toml`
* `[tool.poetry-pyinstaller-plugin]`
* `scripts` (dictionary)
* Where key is the program name and value a path to script or a `PyInstallerTarget` spec
* Example: `prog-name = "my_package/script.py"`
* `certifi` (dictionary)
* `append` (list): List of certificates to include in `certifi.where()`
* `collect` (dictionary)
* `submodules` (list): Collect all submodules for specified package(s) or module(s)
* `data` (list): Collect all data for specified package(s) or module(s)
* `binaries` (list): Collect all binaries for specified package(s) or module(s)
* `all` (list): Collect all submodules, data files, and binaries for specified package(s) or module(s)
`PyinstallerTarget` spec:
* `source` (string): Path to your program entrypoint
* `type` (string, **default:** `onedir`): Type of distribution format. Must be one of `onefile`, `onedir`
* `bundle` (boolean, **default:** `false`): Include executable binary onto wheel
* `noupx` (boolean, **default:** `false`) : Disable UPX archiving
* `strip` (boolean, **default** `false`) : Apply a symbol-table strip to the executable and shared libs (not recommended for Windows)
* `console` (boolean, **default** `false`) : Open a console window for standard i/o (default). On Windows this option has no effect if the first script is a ‘.pyw’ file.
* `windowed` (boolean, **default** `false`) : Windows and Mac OS X: do not provide a console window for standard i/o. On Mac OS this also triggers building a Mac OS .app bundle. On Windows this option is automatically set if the first script is a ‘.pyw’ file. This option is ignored on *NIX systems.
* `icon` (Path, **default** PyInstaller’s icon) : FILE.ico: apply the icon to a Windows executable. FILE.exe,ID: extract the icon with ID from an exe. FILE.icns: apply the icon to the .app bundle on Mac OS. Use “NONE” to not apply any icon, thereby making the OS to show some default
* `uac_admin` (boolean, **default** `false`) : Using this option creates a Manifest that will request elevation upon application start.
* `uac_uiaccess` (boolean, **default** `false`) : Using this option allows an elevated application to work with Remote Desktop.
* `argv_emulation` (boolean, **default** `false`) : Enable argv emulation for macOS app bundles. If enabled, the initial open document/URL event is processed by the bootloader and the passed file paths or URLs are appended to sys.argv.
* `arch` (string, **default** `null`) : Target architecture (macOS only; valid values: x86_64, arm64, universal2).
### Examples
```toml
[tool.poetry-pyinstaller-plugin.scripts]
hello-world = "my_package/main.py"
# Equivalent to
hello-world = { source = "my_package/main.py", type = "onedir", bundle = false }
# Single file bundled in wheel
single-file-bundled = { source = "my_package/main.py", type = "onefile", bundle = true}
# Folder bundled in wheel
folder-bundled = { source = "my_package/main.py", type = "onedir", bundle = true}
[tool.poetry-pyinstaller-plugin.certifi]
# Section dedicated to certifi, required if certificates must be included in certifi store
append = ['certs/my_cert.pem']
[tool.poetry-pyinstaller-plugin.collect]
# Collect all submodules, data files & binaries for 'package_A' and 'package_B'
all = ['package_A', 'package_B']
```
## Usage
Once configured `poetry-pyinstaller-plugin` is attached to the `poetry build` command.
```text
$ poetry build
Building binaries with PyInstaller Python 3.10.12 (main, Nov 20 2023, 15:14:05) [GCC 11.4.0]
- Building hello-world DIRECTORY
- Built hello-world -> 'dist/pyinstaller/hello-world'
- Building single-file-bundled SINGLE_FILE BUNDLED
- Built single-file-bundled -> 'dist/pyinstaller/single-file-bundled'
- Building folder-bundled DIRECTORY BUNDLED
- Built folder-bundled -> 'dist/pyinstaller/folder-bundled'
Building my_package (0.0.0)
- Building sdist
- Built my_package-0.0.0.tar.gz
- Building wheel
- Built my_package-0.0.0-py3-none-any.whl
- Adding single-file-bundled to data scripts my_package-0.0.0-py3-none-any.whl
- Adding folder-bundled to data scripts my_package-0.0.0-py3-none-any.whl
Replacing platform in wheels (manylinux_2_35_x86_64)
- my_package-0.0.0-py3-none-manylinux_2_35_x86_64.whl
```
Expected directory structure:
```text
.
├── build ...................... PyInstaller intermediate build directory
│ ├── folder-bundled
│ ├── hello-world
│ └── single-file-bundled
├── dist ....................... Result of `poetry build` command
│ ├── pyinstaller ............. PyInstaller output
│ │ ├── .specs/ ............ Specs files
│ │ ├── hello-world/
│ │ ├── folder-bundled/
│ │ └── single-file-bundled
│ ├── my_package-0.0.0-py3-none-manylinux_2_35_x86_64.whl ... Wheel with bundled binaries
│ └── my_package-0.0.0.tar.gz ............................... Source archive, binaries are never included
├── pyproject.toml
└── my_package
├── __init__.py
└── main.py
```
## Dependencies notice
Major benefit of this plugin is to create dependency free wheels with executable binaries (including dependencies).
It is then recommended to include your dependencies as optional in your `pyproject.toml`
### Example
```toml
[tool.poetry]
name = "my-package"
[tool.poetry.dependencies]
python = "^3.8"
rich = {version = "^13.7.0", optional = true}
[tool.poetry.extras]
with-deps = ["rich"]
```
Resulting package will not require any dependency except if installed with extra `with-deps`.
```shell
# Installation without dependencies (included in executable binaries)
$ pip install my-package
# Installation with dependencies (If package imported as modules in another project)
$ pip install my-package[with-deps]
```
Bundled binaries must be built with all dependencies installed in build environment.
Raw data
{
"_id": null,
"home_page": "https://github.com/thmahe/poetry-pyinstaller-plugin",
"name": "poetry-pyinstaller-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.8",
"maintainer_email": null,
"keywords": "poetry, plugin, pyinstaller, binary",
"author": "Thomas Mah\u00e9",
"author_email": "contact@tmahe.dev",
"download_url": "https://files.pythonhosted.org/packages/a7/a8/315949fb7066e9396681b75e00b7beeb5365a199efe3e1ea0b181d6c489d/poetry_pyinstaller_plugin-1.1.8.tar.gz",
"platform": null,
"description": "# PyInstaller plugin for Poetry\n\nEasily create executable binaries from your `pyproject.toml` using [PyInstaller](https://pyinstaller.org).\n\n## Features\n* **Multiple distribution formats**\n * **Single file** created in `dist` folder (executable archive)\n * **Folder** created in `dist` folder (containing executable and libraries)\n * **Bundled** executable in platform specific wheels as scripts\n * Both single file & folder distribution type can be bundled in wheels\n\n## Installation\n\nTo install `poetry-pyinstaller-plugin` run the following command:\n```shell\npoetry self add poetry-pyinstaller-plugin\n```\n\nIf you are having troubles to install the plugin please refer to Poetry documentation: https://python-poetry.org/docs/plugins/#using-plugins\n\n## Configuration\n\nAre listed in this sections all options available to configure `poetry-pyinstaller-plugin` in your `pyproject.toml`\n\n* `[tool.poetry-pyinstaller-plugin]`\n * `scripts` (dictionary) \n * Where key is the program name and value a path to script or a `PyInstallerTarget` spec\n * Example: `prog-name = \"my_package/script.py\"`\n * `certifi` (dictionary)\n * `append` (list): List of certificates to include in `certifi.where()`\n * `collect` (dictionary)\n * `submodules` (list): Collect all submodules for specified package(s) or module(s)\n * `data` (list): Collect all data for specified package(s) or module(s)\n * `binaries` (list): Collect all binaries for specified package(s) or module(s)\n * `all` (list): Collect all submodules, data files, and binaries for specified package(s) or module(s)\n\n`PyinstallerTarget` spec:\n* `source` (string): Path to your program entrypoint\n* `type` (string, **default:** `onedir`): Type of distribution format. Must be one of `onefile`, `onedir`\n* `bundle` (boolean, **default:** `false`): Include executable binary onto wheel\n* `noupx` (boolean, **default:** `false`) : Disable UPX archiving\n* `strip` (boolean, **default** `false`) : Apply a symbol-table strip to the executable and shared libs (not recommended for Windows)\n* `console` (boolean, **default** `false`) : Open a console window for standard i/o (default). On Windows this option has no effect if the first script is a \u2018.pyw\u2019 file.\n* `windowed` (boolean, **default** `false`) : Windows and Mac OS X: do not provide a console window for standard i/o. On Mac OS this also triggers building a Mac OS .app bundle. On Windows this option is automatically set if the first script is a \u2018.pyw\u2019 file. This option is ignored on *NIX systems.\n* `icon` (Path, **default** PyInstaller\u2019s icon) : FILE.ico: apply the icon to a Windows executable. FILE.exe,ID: extract the icon with ID from an exe. FILE.icns: apply the icon to the .app bundle on Mac OS. Use \u201cNONE\u201d to not apply any icon, thereby making the OS to show some default\n* `uac_admin` (boolean, **default** `false`) : Using this option creates a Manifest that will request elevation upon application start.\n* `uac_uiaccess` (boolean, **default** `false`) : Using this option allows an elevated application to work with Remote Desktop.\n* `argv_emulation` (boolean, **default** `false`) : Enable argv emulation for macOS app bundles. If enabled, the initial open document/URL event is processed by the bootloader and the passed file paths or URLs are appended to sys.argv.\n* `arch` (string, **default** `null`) : Target architecture (macOS only; valid values: x86_64, arm64, universal2).\n\n### Examples\n\n```toml\n[tool.poetry-pyinstaller-plugin.scripts]\nhello-world = \"my_package/main.py\"\n# Equivalent to\nhello-world = { source = \"my_package/main.py\", type = \"onedir\", bundle = false }\n\n# Single file bundled in wheel\nsingle-file-bundled = { source = \"my_package/main.py\", type = \"onefile\", bundle = true}\n\n# Folder bundled in wheel\nfolder-bundled = { source = \"my_package/main.py\", type = \"onedir\", bundle = true}\n\n[tool.poetry-pyinstaller-plugin.certifi]\n# Section dedicated to certifi, required if certificates must be included in certifi store\nappend = ['certs/my_cert.pem']\n\n[tool.poetry-pyinstaller-plugin.collect]\n# Collect all submodules, data files & binaries for 'package_A' and 'package_B'\nall = ['package_A', 'package_B']\n```\n\n## Usage\n\nOnce configured `poetry-pyinstaller-plugin` is attached to the `poetry build` command.\n```text\n$ poetry build\nBuilding binaries with PyInstaller Python 3.10.12 (main, Nov 20 2023, 15:14:05) [GCC 11.4.0]\n - Building hello-world DIRECTORY\n - Built hello-world -> 'dist/pyinstaller/hello-world'\n - Building single-file-bundled SINGLE_FILE BUNDLED\n - Built single-file-bundled -> 'dist/pyinstaller/single-file-bundled'\n - Building folder-bundled DIRECTORY BUNDLED\n - Built folder-bundled -> 'dist/pyinstaller/folder-bundled'\nBuilding my_package (0.0.0)\n - Building sdist\n - Built my_package-0.0.0.tar.gz\n - Building wheel\n - Built my_package-0.0.0-py3-none-any.whl\n - Adding single-file-bundled to data scripts my_package-0.0.0-py3-none-any.whl\n - Adding folder-bundled to data scripts my_package-0.0.0-py3-none-any.whl\nReplacing platform in wheels (manylinux_2_35_x86_64)\n - my_package-0.0.0-py3-none-manylinux_2_35_x86_64.whl\n```\n\nExpected directory structure:\n```text\n.\n\u251c\u2500\u2500 build ...................... PyInstaller intermediate build directory\n\u2502 \u251c\u2500\u2500 folder-bundled\n\u2502 \u251c\u2500\u2500 hello-world\n\u2502 \u2514\u2500\u2500 single-file-bundled \n\u251c\u2500\u2500 dist ....................... Result of `poetry build` command\n\u2502 \u251c\u2500\u2500 pyinstaller ............. PyInstaller output\n\u2502 \u2502 \u251c\u2500\u2500 .specs/ ............ Specs files\n\u2502 \u2502 \u251c\u2500\u2500 hello-world/\n\u2502 \u2502 \u251c\u2500\u2500 folder-bundled/ \n\u2502 \u2502 \u2514\u2500\u2500 single-file-bundled\n\u2502 \u251c\u2500\u2500 my_package-0.0.0-py3-none-manylinux_2_35_x86_64.whl ... Wheel with bundled binaries\n\u2502 \u2514\u2500\u2500 my_package-0.0.0.tar.gz ............................... Source archive, binaries are never included\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 my_package\n \u251c\u2500\u2500 __init__.py\n \u2514\u2500\u2500 main.py\n```\n\n## Dependencies notice\n\nMajor benefit of this plugin is to create dependency free wheels with executable binaries (including dependencies).\n\nIt is then recommended to include your dependencies as optional in your `pyproject.toml`\n\n### Example\n```toml\n[tool.poetry]\nname = \"my-package\"\n\n[tool.poetry.dependencies]\npython = \"^3.8\"\nrich = {version = \"^13.7.0\", optional = true}\n\n[tool.poetry.extras]\nwith-deps = [\"rich\"]\n```\n\nResulting package will not require any dependency except if installed with extra `with-deps`.\n```shell\n# Installation without dependencies (included in executable binaries)\n$ pip install my-package\n\n# Installation with dependencies (If package imported as modules in another project)\n$ pip install my-package[with-deps] \n```\n\nBundled binaries must be built with all dependencies installed in build environment.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Poetry plugin to build and/or bundle executable binaries with PyInstaller",
"version": "1.1.8",
"project_urls": {
"Homepage": "https://github.com/thmahe/poetry-pyinstaller-plugin",
"Repository": "https://github.com/thmahe/poetry-pyinstaller-plugin"
},
"split_keywords": [
"poetry",
" plugin",
" pyinstaller",
" binary"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3d4c8edf45b6aacbf7b61166ebceca3ac7ce369413ae005f10241cc8eb28c01b",
"md5": "db2ae7e70cdc5e439dd7ed6d30360eac",
"sha256": "7805fac84a954938945dc37996d8dd8347533cec0861e2ec9a617380ea6533e6"
},
"downloads": -1,
"filename": "poetry_pyinstaller_plugin-1.1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "db2ae7e70cdc5e439dd7ed6d30360eac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8",
"size": 10136,
"upload_time": "2024-04-11T19:19:55",
"upload_time_iso_8601": "2024-04-11T19:19:55.245572Z",
"url": "https://files.pythonhosted.org/packages/3d/4c/8edf45b6aacbf7b61166ebceca3ac7ce369413ae005f10241cc8eb28c01b/poetry_pyinstaller_plugin-1.1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a7a8315949fb7066e9396681b75e00b7beeb5365a199efe3e1ea0b181d6c489d",
"md5": "9f1fb1c0ecc1fc644df5993c0b055932",
"sha256": "a9583a7662e7659033bdffd38b13ce4074ea74cfee6a9cde8a62d86ebbce4d71"
},
"downloads": -1,
"filename": "poetry_pyinstaller_plugin-1.1.8.tar.gz",
"has_sig": false,
"md5_digest": "9f1fb1c0ecc1fc644df5993c0b055932",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8",
"size": 7713,
"upload_time": "2024-04-11T19:19:56",
"upload_time_iso_8601": "2024-04-11T19:19:56.864674Z",
"url": "https://files.pythonhosted.org/packages/a7/a8/315949fb7066e9396681b75e00b7beeb5365a199efe3e1ea0b181d6c489d/poetry_pyinstaller_plugin-1.1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-11 19:19:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thmahe",
"github_project": "poetry-pyinstaller-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "poetry-pyinstaller-plugin"
}
JSON
