Global options¶

The following options can be set for all tasks in a project directly under [tool.poe]. These are called global options, in contrast with task options.

envdict[str, str] 📖: Define environment variables to be exposed to all tasks. These can be extended on the task level.
envfilestr | list[str] 📖: Link to one or more files defining environment variables to be exposed to all tasks.
executorstr | dict[str, str] 📖: Specify the default executor type and/or configuration for all tasks in this project.
includestr | dict[str, str] | list[str | dict[str, str]] | 📖: Specify one or more other toml or json files to load tasks from.
include_scriptstr | dict[str, str] | list[str | dict[str, str]] 📖: Load dynamically generated tasks from one or more python functions. This is similar to the include global option, except instead of providing paths to config files, one can reference python functions that generate task config, using the same syntax as for script tasks.
shell_interpreterstr | list[str] 📖: Change the default interpreter to use for executing shell tasks.
poetry_commandstr 📖: Change the name of the task poe registers with poetry when used as a plugin.
poetry_hooksdict[str, str] 📖: Register tasks to run automatically before or after other poetry CLI commands.
verbosityint: Set the default verbosity level for tasks in this project. The default value is 0, providing the -v global CLI option increases it by 1, whereas the -q global CLI option decreases it by 1.
default_task_type"cmd" | "expr" | "ref" | "script" | "shell": When a task is declared as a string (instead of a table), then it is interpreted as the default task type, which will be "cmd" unless otherwise specified.
default_array_task_typestr: When a task is declared as an array (instead of a table), then it is interpreted as the default array task type, which will be "sequence" unless otherwise specified. Valid options are "sequence" or "parallel".
default_array_item_task_type"cmd" | "expr" | "ref" | "script" | "shell": When a task is declared as a string inside an array (e.g. inline in a sequence task), then it is interpreted as the default array item task type, which will be "ref" unless otherwise specified.

Global environment variables¶

You can configure environment variables to be set for all poe tasks in the pyproject.toml file by specifying tool.poe.env like so

[tool.poe.env]
VAR1 = "FOO"
VAR2 = "BAR BAR BLACK ${FARM_ANIMAL}"

The example above also demonstrates how – as with env vars defined at the task level – posix variable interpolation syntax may be used to define global env vars with reference to variables already defined in the host environment or in a referenced env file.

As with the task level option, you can indicated that a variable should only be set if not already set like so:

[tool.poe.env]
VAR1.default = "FOO"

Loading external environment variables¶

You can also specify an env file (with bash-like syntax) to load for all tasks like so:

.env¶

 STAGE=dev
 PASSWORD='!@#$%^&*('

pyproject.toml¶

 [tool.poe]
 envfile = ".env"

The envfile global option also accepts a list of env files like so:

[tool.poe]
envfile = ["standard.env", "local.env"]

In this case the referenced files will be loaded in the given order.

Important

The envfile option is also available with the same capabilities at the task level.

Optional env files¶

Normally poe will emit a warning if a specified envfile is not found. If you consider an envfile to be optional, you can suppress these warnings by configuring the file path (or paths) under the optional prefix like so:

[tool.poe]
envfile.optional = ".env"

You can combine optional and expected envfiles like so:

[tool.poe.envfile]
expected = ["shared.env"]
optional = ["local.env"]

In this example shared.env is considered mandatory, whereas local.env may be absent without generating noise. Using envfile = ".env" remains equivalent to setting envfile.expected = ".env" explicitly.

Resolving env file paths¶

Normally envfile paths are resolved relative to the project root (that is the parent directory of the pyproject.toml). However when working with a monorepo it can also be useful to specify the path relative to the root of the git repository, which can be done by referencing the POE_GIT_DIR or POE_GIT_ROOT variables like so:

[tool.poe]
envfile = "${POE_GIT_DIR}/.env"

See the documentation on Special variables for a full explanation of how these variables work.

Note

Environment variables loaded from env files have higher precedence than any inherited from the host environment, but lower precedence than env defined directly in the pyproject.toml file. Similarly optional env files are loaded after expected ones, so variables defined in optional files can override those defined in expected files.

Configure the executor¶

You can configure poe to use a specific executor by setting tool.poe.executor. Valid values include:

auto: to automatically use the most appropriate of the following executors in order
poetry: to run tasks in the poetry managed environment
uv: to run tasks in an uv environment
virtualenv: to run tasks in the indicated virtualenv (or else “./.venv” or “./venv” if present)
simple: to run tasks without doing any specific environment setup

The default behavior is auto.

You specify a different executor to use as a global option, task level option, or at runtime with the --executor cli option.

For example you can make your whole project use the simple executor (no environment integration) by default like so:

[tool.poe]
executor = "simple"

Which is a short hand for the following table form which is required in order to pass options to the executor:

[tool.poe.executor]
type = "simple"

Important

You can also configure the executor at the task level, which will have higher precedence. Alternatively you can override the executor type at runtime by passing the --executor CLI option (before the task name) with the name of the executor to use, or the

Uv Executor¶

The uv executor can be configured with the following options, which translate into passing the corresponding CLI option to the uv run command:

extrastr | list[str] 📖: Include optional dependencies from the specified extra name.
groupstr | list[str] 📖: Include dependencies from the specified dependency group.
no-groupstr | list[str] 📖: Disable the specified dependency group.
withstr | list[str] 📖: Run with the given packages installed.
isolatedbool 📖: Run the command in an isolated virtual environment.
no-syncbool 📖: Avoid syncing the virtual environment.
lockedbool 📖: Run without updating the uv.lock file.
frozenbool 📖: Run without updating the uv.lock file.
no-projectbool 📖: Avoid discovering the project or workspace.
pythonstr 📖: The Python interpreter to use for the run environment.

[tool.poe.executor]
type = "uv"
run_options = ["--isolated"]

Common use cases for uv include:

Isolated environments: --isolated to prevent accessing global packages
Python version selection: --python 3.11 to use a specific Python version
Additional dependencies: --with httpx --with pytest to add packages on-the-fly

Example with task-level options:

[tool.poe.executor]
type = "uv"

[tool.poe.tasks.test-py311]
cmd = "pytest tests"
executor_run_options = ["--isolated", "--python", "3.11"]

[tool.poe.tasks.test-py312]
cmd = "pytest tests"
executor_run_options = ["--isolated", "--python", "3.12"]

This feature enables you to replace tools like tox by creating task variants for different Python versions or environments. See the Replacing tox with uv and Poe the Poet for a detailed guide on replacing tox.

Virtualenv Executor¶

The virtualenv executor can be configured with the following options:

locationbool: The path of the virtual environment to use. Defaults to ./venv or ./.venv.

[tool.poe.executor]
type = "virtualenv"
location = "myvenv"

If the virtualenv location is a relative path then it is resolved relative to the project root (the parent directory of the pyproject.toml file. However in a monorepo project it may also be defined relative to the git repo root by templating these special environment variables like so:

[tool.poe.executor]
type = "virtualenv"
location = "${POE_GIT_DIR}/myvenv"

Change the default shell interpreter¶

Normally shell tasks are executed using a posix shell by default (see section for shell tasks above). This default can be overridden to something else by setting the shell_interpreter global option. In the following example we configure all shell tasks to use fish by default.

tool.poe.shell_interpreter = "fish"

[tool.poe.tasks.fibonacci]
help = "Output the fibonacci sequence up to 89"
shell = """
  function fib --argument-names max n0 n1
    if test $max -ge $n0
      echo $n0
      fib $max $n1 (math $n0 + $n1)
    end
  end

  fib 89 1 1
"""

Default command verbosity¶

You can alter the verbosity level for poe commands by passing --quiet / -q (which decreases verbosity) or --verbose / -v (which increases verbosity) on the CLI.

If you want to change the default verbosity level for all commands, you can use the tool.poe.verbose option in pyproject.toml like so:

[tool.poe]
verbosity = -1

-1 is the quietest and 1 is the most verbose. 0 is the default.

Note that the command line arguments are incremental: -q subtracts one from the default verbosity, and -v adds one. So setting the default verbosity to -1 and passing -v -v on the command line is equivalent to setting the verbosity to 0 and just passing -v.

Change the default task type¶

By default tasks defined as strings are interpreted as shell commands, and script tasks require the more verbose table syntax to specify. For example:

my_cmd_task = "cmd args"
my_script_task = { "script" = "my_package.my_module:run" }

This behaviour can be reversed by setting the default_task_type option in your pyproject.toml like so:

[tool.poe]
default_task_type = "script"

[tool.poe.tasks]
my_cmd_task = { "cmd" = "cmd args" }
my_script_task = "my_package.my_module:run"

Run poe from anywhere¶

By default poe will detect when you’re inside a project with a pyproject.toml in the root. However if you want to run it from elsewhere then that is supported by using the -C option to specify an alternate location for the toml file. The task will run with the given location as the current working directory.

In all cases the path to project root (where the pyproject.toml resides) will be available as $POE_ROOT within the command line and process.