Skip to content

Environment management with venv

The default environment manager used by Briefcase to manage the installation of application requirements is the venv package built into Python's standard library.

When venv is used to manage your app environment, an official Python or Briefcase-supplied Python support package will be used for your app.

Prerequisites

There are no additional pre-requisites for using venv to manage application environments. Requirements will be installed with pip; Briefcase will use the version of pip that is installed in the environment where Briefcase is executed. venv can be used to build apps on all platforms.

Configuration

No additional configuration is needed to use venv as the environment manager for your application.

However, you can explicitly specify the use of venv by adding env_manager = "venv" to your app configuration. This can be done as a global setting (in [tool.briefcase] section) or in a per-app setting (in the [tool.briefcase.app.myapp] section for myapp).

Specifying requirements

When venv is used as an environment manager, requirements are installed using pip. The values provided to requires and test_requires must be in a pip-compatible format. The following would be examples of legal specifiers:

  • A bare package name: 

    requires = ["pillow"]

  • A package name with version specifier: 

    requires = ["pillow==9.1.0"]

  • A package with a platform specifier: 

    requires = ["pillow==9.1.0; sys_platform == 'darwin'"]

  • A Git repository: 

    requires = ["git+https://github.com/beeware/briefcase.git"]

  • A local directory: 

    requires = [
    "../mysrc/myapp",
    "./local/otherapp",
    "/usr/local/fullapp",
]
    When in development mode, a reference to a local directory will be installed editable. Any changes made to the code in the original location will be picked up automatically the next time you start your application in development mode. When generating a final application, editable mode will not be used.

  • Local wheel file: 

    requires = [
    "../mysrc/myapp-1.2.3.py3-none-any.whl",
    "./local/otherapp-1.2.3.py3-none-any.whl",
    "/usr/local/fullapp-1.2.3.py3-none-any.whl",
]