Usage#
CLI#
usage: pw [-h] [--version] [--toml TOML] [--install-dir INSTALL_DIR]
[--force-install] [--clean] [--install-context tool-context]
[--verbose] [--quiet] [--info]
[--add [context:]<package>,<package>...] [--lock] [--install-px]
[--upgrade]
...
Execute commands or aliases defined in the [tool.pyprojectx] section of
pyproject.toml. Use the -i or --info option to see available tools and
aliases.
positional arguments:
command The command/alias with optional arguments to execute.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--toml, -t TOML The toml config file. Defaults to 'pyproject.toml' in
the same directory as the pw script.
--install-dir INSTALL_DIR
The directory where all tools (including pyprojectx)
are installed; defaults to the PYPROJECTX_INSTALL_DIR
environment value if set, else '.pyprojectx' in the
same directory as the invoked pw script.
--force-install, -f Force clean installation of the virtual environment
used to run cmd, if any.
--clean, -c Clean .pyprojectx directory by removing all but the
current versions of pyprojectx and context virtual
environments.
--install-context tool-context
Install a tool context without actually running any
command.
--verbose, -v Give more output. This option is additive and can be
used up to 2 times.
--quiet, -q Suppress output.
--info, -i Show the configuration details of a command instead of
running it. If no command is specified, a list with
all available tools and aliases is shown.
--add [context:]<package>,<package>...
Add one or more packages to a tool context. If no
context is specified, the packages are added to the
main context. Packages can be specified as in 'pip
install', except that a ',' can't be used in the
version specification.
--lock Write all dependencies of all tool contexts to
'pw.lock' to guarantee reproducible outcomes.
--install-px Install the px and pxg scripts in your home directory.
--upgrade Download the latest pyprojectx wrapper scripts.
Common workflows#
Running a tool for the first time#
When you run a tool that isn't installed yet, Pyprojectx automatically creates its virtual environment and installs all requirements:
px ruff check
# first run: installs ruff, then runs the check
# subsequent runs: ruff is already available, runs immediately
Adding a new tool#
Use --add to add tools to pyproject.toml in one step:
./pw --add httpie
./pw http pie.dev/get
Upgrading tools (re-locking)#
When using a lock file, upgrade all tools to the latest compatible version by combining --lock with --force-install:
./pw --lock -f
This resolves fresh versions, recreates the virtual environments, and updates the pw.lock file.
Forcing reinstallation#
If a virtual environment gets corrupted or you want to ensure a clean state:
./pw --force-install ruff check
# or reinstall a specific context without running a command
./pw -f --install-context main
Install the global px script#
Pyprojectx provides a small px script that delegates everything to the pw wrapper script.
The pw script is searched for in the current working directory and its parents.
When added to your PATH, you can replace ./pw with the shorter px.
This also works from subdirectories: ../../pw can also be replaced with px
To install:
./pw --install-px
pw --install-px
Global tools#
Besides the px script, pw --install-px also installs the pxg script.
pxg can be used as a lightweight pipx to install/run tools globally. It provides a default uv, f.e. pxg uv --help will show the help.
Example: make http requests with httpie:
pxg --add httpie
pxg http POST pie.dev/post hello=world
The global setup can be configured in ~/.pyprojectx/global/pyproject.toml.
Uninstalling all global tools is just a matter of removing the global directory:
rm -rf ~/.pyprojectx/global/.pyprojectx