Skip to content

Pyprojectx ALL-INCLUSIVE PYTHON PROJECTS

Introduction#

Pyprojectx makes it easy to create all-inclusive Python projects; no need to install any tools upfront, not even Pyprojectx itself!

Feature highlights#

  • Reproducible builds by treating tools and utilities as (versioned) dev-dependencies
  • No global installs, everything is stored inside your project directory (like npm's node_modules)
  • Bootstrap your entire build process with a small wrapper script (like Gradle's gradlew wrapper)
  • Configure shortcuts for routine tasks
  • Simple configuration in pyproject.toml

Projects can be build/tested/used immediately without explicit installation nor initialization:

git clone https://github.com/pyprojectx/px-demo.git
# the demo project uses uv as build tool, but has branches for pdm and poetry
cd px-demo
./pw build

git clone https://github.com/pyprojectx/px-demo.git
# the demo project uses uv as build tool, but has branches for pdm and poetry
cd px-demo
pw build

Clone and Build

Installation#

One of the key features is that there is no need to install anything explicitly (except a Python 3.8+ interpreter).

cd into your project directory and download the wrapper scripts:

curl -LO https://github.com/pyprojectx/pyprojectx/releases/latest/download/wrappers.zip && unzip -o wrappers.zip && rm -f wrappers.zip

Invoke-WebRequest https://github.com/pyprojectx/pyprojectx/releases/latest/download/wrappers.zip -OutFile wrappers.zip; Expand-Archive -Force -Path wrappers.zip -DestinationPath .; Remove-Item -Path wrappers.zip

With the wrapper scripts in place, you can start adding tools:

# initialize a uv project in a (empty) directory without pyproject.toml
./pw uv init
# add common tools to the project, including uv
./pw --add uv,ruff,pre-commit,px-utils
# have uv create the virtual environment and install the dependencies
./pw uv sync
# call the main script to show that the project is set up correctly
./pw uv run main.py
# lock the tool versions for reproducible builds
./pw --lock

# initialize a uv project in a (empty) directory without pyproject.toml
pw uv init
# add common tools to the project, including uv
pw --add uv,ruff,pre-commit,px-utils
# have uv create the virtual environment and install the dependencies
pw uv sync
# call the main script to show that the project is set up correctly
pw uv run main.py
# lock the tool versions for reproducible builds
pw --lock

Tip: Add the wrapper scripts to version control

When using Git: 

git add pw pw.bat
git update-index --chmod=+x pw
echo .pyprojectx/ >> .gitignore

Tip: Install the px utility script

You can copy a small script to .pyprojectx in your home directory. 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

./pw --install-px

pw --install-px

If you don't want to prefix every command with px or ./pw, you can activate a tool context.