{"id":16651923,"url":"https://github.com/syegulalp/pydeploy","last_synced_at":"2025-09-16T19:31:32.040Z","repository":{"id":195421535,"uuid":"692874086","full_name":"syegulalp/pydeploy","owner":"syegulalp","description":"experimental project to allow Python programs to be deployed as standalone applications (currently only on Microsoft Windows)","archived":false,"fork":false,"pushed_at":"2024-10-19T13:08:29.000Z","size":64,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-27T19:42:25.460Z","etag":null,"topics":["python","python-deployment","python-packaging"],"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/syegulalp.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-09-17T20:55:00.000Z","updated_at":"2024-10-20T21:45:39.000Z","dependencies_parsed_at":"2023-09-17T21:55:57.184Z","dependency_job_id":"9824c4ca-bf5d-42e2-a336-fc9c264f01ed","html_url":"https://github.com/syegulalp/pydeploy","commit_stats":null,"previous_names":["syegulalp/pydeploy"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syegulalp%2Fpydeploy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syegulalp%2Fpydeploy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syegulalp%2Fpydeploy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syegulalp%2Fpydeploy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syegulalp","download_url":"https://codeload.github.com/syegulalp/pydeploy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233288152,"owners_count":18653430,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["python","python-deployment","python-packaging"],"created_at":"2024-10-12T09:27:02.094Z","updated_at":"2025-09-16T19:31:32.025Z","avatar_url":"https://github.com/syegulalp.png","language":"Python","readme":"\u003e This project is still in its very early stages. This documentation is correspondingly rough and incomplete.\r\n\r\nPyDeploy is an *experimental* project to allow Python programs to be deployed as standalone applications (currently only on Microsoft Windows), provided they are written to be `pip install`-able by way of a `pyproject.toml` file.\r\n\r\nInstead of using the PyInstaller approach, which is highly customized, PyDeploy uses Python-native tooling and procedures. It uses the Python redistributable package to create a self-contained Python instance, and `pip install`s the needed files into it.\r\n\r\nThe end result should not cause antivirus systems to complain as it only uses the binaries already signed and redistributed with Python.\r\n\r\nPyDeploy has no dependencies other than the standard library.\r\n\r\n# Usage\r\n\r\n## 1. Create a `pip install`-able project using `pyproject.toml` and the proper project layout\r\n\r\nBasically, make your app into a pip-installable package using `pyproject.toml`. If you haven't learned how to do this yet, I highly recommend it. The `examples` directory will furnish some examples for how to do this for various kinds of programs.\r\n\r\nMake a virtual environment for your project, and ideally use a `src` directory for your application code. You should also have a `pyproject.toml` file along these lines:\r\n\r\n```toml\r\n[project]\r\nname = \"myapp\"\r\nversion = \"0.1\"\r\n\r\n[build-system]\r\nrequires = [\"setuptools\", \"wheel\"]\r\nbuild-backend = \"setuptools.build_meta\"\r\n\r\n[project.scripts]\r\nmyproject = \"myproject:main\"\r\n```\r\n\r\nNote that the `project.scripts` section will be used by PyDeploy to determine what `.exe` entry points to make. In this case, we will have a CLI entry point named `myproject.exe` in our deployable app directory.\r\n\r\n*Make sure your application works as a `pip install`-able project **before** you use PyDeploy!* Install your app into its own venv using the `-e` (\"editable\") flag, and test it that way.\r\n\r\nIf you want to copy *data directories or other artifacts* over to the target, see the section \"Using the `tool.pydeploy` section of `pyproject.toml` to configure build behavior\" below.\r\n\r\n\r\n## 2. Install PyDeploy into project venv\r\n\r\nRight now PyDeploy is not on PyPI, so you'll need to install directly from Github:\r\n\r\n`pip install git+https://github.com/syegulalp/pydeploy`\r\n\r\n## 3. Run pydeploy on your project\r\n\r\nWhile in the project's root, type:\r\n\r\n`pydeploy .`\r\n\r\n(You can also use `pd` for short.)\r\n\r\nIf you want to supply an explicit path to a project:\r\n\r\n`pydeploy \u003cproject_dir\u003e`\r\n\r\nThis will analyze the `pyproject.toml` file and create a subdirectory named `deploy_\u003cversion\u003e`, where `\u003cversion\u003e` is the Python version for the currently active venv.\r\n\r\nAfter the analysis and build process finishes you should have a `dist` subdirectory that contains your deployed project, along with a `.zip` archive of the project.\r\n\r\nThe resulting archive may be fairly large even for a simple \"hello world\" app, but I will introduce mechanisms in the future to make the deployed app less bulky by removing unused libraries.\r\n\r\n# Command line options\r\n\r\nPydeploy has a few command line switches, supplied along with the directory name for the project to build (the default is the current working directory):\r\n\r\n* `-h`: Print help.\r\n* `-x`: Does not build zip archives of the application files. Normally all Python files are packed into a zip file, but the original layout of Python files can be preserved with this option. Note that if PyDeploy detects a mix of Python and other files in an app directory, it will fall back to this behavior for that app directory.\r\n* `-s`: Omit some of the larger and less commonly used standard library modules, which reduces the footprint of the redistributable. The variables `remove_stdlib_for_smallify` and `remove_for_smallify` list the libraries and modules in question. (This will eventually be replaced with a more fine-grained mechanism.)\r\n* `-q`: Don't show output from `pip install`, just the basic log info.\r\n\r\n# Including program assets\r\n\r\nMany programs include data files that are not actually code -- for instance, a game with graphics and sound assets. Including these with your project is possible, but the best way to do this may requre you to slightly reorganize your project.\r\n\r\nWhen you build a `pydeploy` project, you can create subdirectories that are immediate children of the program's current working directory:\r\n\r\n```\r\nyour_program\r\n    /libs # this contains the Python distribution\r\n    /data # your program's data directory\r\n    your_program.exe\r\n```\r\n\r\nThis makes those directories easy to locate, as they are just children of the current working directory.\r\n\r\nIn your source repository, the best place for the data directory is in a subdirectory that mirrors its location, like this:\r\n\r\n```\r\nyour_program_repo\r\n    /src # your program data\r\n    /data\r\n    pyproject.toml\r\n```\r\n\r\nThis keeps your data from being comingled with your program source.\r\n\r\nSince you need to create an entry point to start your program, you can then launch the entry point in the root directory of your program's repository (the current working directory), and have the data directory also detected as a child of that current working directory.\r\n\r\nTo copy the data directory (or directories) to your deployement, you'll use `data_dirs` described in the next section.\r\n\r\nYou can see an example layout of a project that follows this pattern in the directory `examples/pygame_asset`.\r\n\r\n# Using the `tool.pydeploy` section of `pyproject.toml` to configure build behavior\r\n\r\nYou can configure some of Pydeploy's behaviors by adding a `tool.pydeploy` section to your `pyproject.toml` file.\r\n\r\n```toml\r\n[tool.pydeploy]\r\ndata_dirs = [[\"source_dir\", \"target_dir\"]]\r\nomit_files = [\"libs/app/module/*.c\", \"libs/app/module/*.pyc\"]\r\n```\r\n\r\n## `data_dirs`\r\n\r\n`data_dirs` is used to copy files from your source project tree, such as data files, into your distribution.\r\n\r\nTo use `data_dirs`, provide a list of two-item lists. The first item is the source directory in your project tree (with `pyproject.toml` as the root); the second item is the target directory with the executable directory as the root. (This is the directory that will by default be the current working directory when your app is launched.)\r\n\r\n## `omit_files`\r\n\r\n`omit_files` is a list of `glob` patterns, starting from the root of the distribution directory. Files that match these patterns are removed from the distribution right before the .zip-archiving process. You can use this to remove things like build artfacts or other unwanted files from your shipped package.\r\n\r\n# Tips\r\n\r\n## Examples\r\n\r\nThe `examples` directory contains scaffolding examples for a few common project types -- a simple CLI, a windowed app using TKinter or Pygame, etc. This gallery will be expanded with time.\r\n\r\n## Use an `__init__.py` in your application package's source directory\r\n\r\nSome people encounter a problem where the editable install of their program works fine when they run it via the entry point, but the `pydeploy`-ed version crashes with an error like this:\r\n\r\n```\r\nTraceback (most recent call last):\r\n  File \"\u003cfrozen runpy\u003e\", line 198, in _run_module_as_main\r\n  File \"\u003cfrozen runpy\u003e\", line 88, in _run_code\r\n  File \"F:\\Dev\\myapp\\deploy_3.13.5\\dist\\myapp.exe\\__main__.py\", line 4, in \u003cmodule\u003e\r\n    from myapp.main import main\r\nModuleNotFoundError: No module named 'myapp'\r\n```\r\n\r\nTo that end, if you don't have an `__init__.py` in  the package's source root (e.g., `/src/myapp`), you need to add one. An empty one should work fine.\r\n\r\n# Todo\r\n\r\n* Support for including TKinter (not included with embedded redistributable)\r\n* Support for excluding specific modules or submodules from apps or stdlib, as opposed to just files\r\n\r\n# License\r\n\r\nMIT","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyegulalp%2Fpydeploy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyegulalp%2Fpydeploy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyegulalp%2Fpydeploy/lists"}