Skip to content

Project structure and files

The pyproject.toml

Python project metadata is defined in a pyproject.toml file. fyn requires this file to identify the root directory of a project.

Tip

fyn init can be used to create a new project. See Creating projects for details.

A minimal project definition includes a name and version:

pyproject.toml
[project]
name = "example"
version = "0.1.0"

Additional project metadata and configuration includes:

The project environment

When working on a project with fyn, fyn will create a virtual environment as needed. While some fyn commands will create a temporary environment (e.g., fyn run --isolated), fyn also manages a persistent environment with the project and its dependencies in a .venv directory next to the pyproject.toml. It is stored inside the project to make it easy for editors to find — they need the environment to give code completions and type hints. It is not recommended to include the .venv directory in version control; it is automatically excluded from git with an internal .gitignore file.

To run a command in the project environment, use fyn run. Alternatively the project environment can be activated as normal for a virtual environment.

When fyn run is invoked, it will create the project environment if it does not exist yet or ensure it is up-to-date if it exists. The project environment can also be explicitly created with fyn sync. See the locking and syncing documentation for details.

It is not recommended to modify the project environment manually, e.g., with fyn pip install. For project dependencies, use fyn add to add a package to the environment. For one-off requirements, use fynx or fyn run --with.

Tip

If you don't want fyn to manage the project environment, set managed = false to disable automatic locking and syncing of the project. For example:

pyproject.toml
[tool.fyn]
managed = false

The lockfile

fyn creates a fyn.lock file next to the pyproject.toml.

fyn.lock is a universal or cross-platform lockfile that captures the packages that would be installed across all possible Python markers such as operating system, architecture, and Python version.

Unlike the pyproject.toml, which is used to specify the broad requirements of your project, the lockfile contains the exact resolved versions that are installed in the project environment. This file should be checked into version control, allowing for consistent and reproducible installations across machines.

A lockfile ensures that developers working on the project are using a consistent set of package versions. Additionally, it ensures when deploying the project as an application that the exact set of used package versions is known.

The lockfile is automatically created and updated during fyn invocations that use the project environment, i.e., fyn sync and fyn run. The lockfile may also be explicitly updated using fyn lock.

fyn.lock is a human-readable TOML file but is managed by fyn and should not be edited manually. The fyn.lock format is specific to fyn and not usable by other tools.

Relationship to pylock.toml

In PEP 751, Python standardized a new resolution file format, pylock.toml.

pylock.toml is a resolution output format intended to replace requirements.txt (e.g., in the context of fyn pip compile, whereby a "locked" requirements.txt file is generated from a set of input requirements). pylock.toml is standardized and tool-agnostic, such that in the future, pylock.toml files generated by fyn could be installed by other tools, and vice versa.

Some of fyn's functionality cannot be expressed in the pylock.toml format; as such, fyn will continue to use the fyn.lock format within the project interface.

However, fyn supports pylock.toml as an export target and in the fyn pip CLI. For example:

  • To export a fyn.lock to the pylock.toml format, run: fyn export -o pylock.toml
  • To generate a pylock.toml file from a set of requirements, run: fyn pip compile requirements.in -o pylock.toml
  • To install from a pylock.toml file, run: fyn pip sync pylock.toml or fyn pip install -r pylock.toml