Installation

Requirements

  • Python: 3.9+ for the bootstrap script, 3.10+ for managed environments

  • uv: 0.5.0 or later (auto-installed if not found)

Which method is right for you?

  • Starting a new project? → Download appenv directly

  • Want the easiest setup? → Use uvx (requires PyPI publication)

  • No internet on target machine? → Copy appenv.py manually

  • Want to develop appenv itself? → Clone the repository

All methods give you the same ./appenv file — the only difference is how you get it.

Download appenv directly

Transparent, no magic, one file:

mkdir myproject && cd myproject
curl -sL https://raw.githubusercontent.com/flyingcircusio/appenv/master/src/appenv.py -o appenv
chmod +x appenv
./appenv init

Pin to a specific version by using a release tag URL:

curl -sL https://github.com/flyingcircusio/appenv/raw/v1.0.0/src/appenv.py -o appenv

uvx (easiest, requires PyPI)

uvx is part of uv — the easiest way to start:

mkdir myproject && cd myproject

# appenv init is interactive
# Answer:
# httpie as dependency
# http as binary
uvx appenv init
./http

What just happened?

  • appenv installed itself inplace by adding the ./appenv script

  • init created pyproject.toml and a symlink http → appenv

  • ./http set up the venv with pinned versions from uv.lock, then ran the http binary

The repository now contains:

myproject/
├── appenv          # The appenv script (single file, committed to git)
├── http -> appenv  # Runs the `http` binary from installed deps
├── pyproject.toml  # Project config and dependency list
└── uv.lock         # Exact versions of all dependencies (committed to git)

Prereleases

If appenv is not yet on stable PyPI, use:

uvx --prerelease allow appenv init

Copy without network access

# On a machine with internet
curl -sL https://raw.githubusercontent.com/flyingcircusio/appenv/master/src/appenv.py -o appenv

# Transfer appenv to target machine (USB, scp, etc.)
scp appenv targethost:~/myproject/

# On the target machine
chmod +x appenv
./appenv init

Cloning the repository

This is for developing appenv itself, not for creating projects.

git clone https://github.com/flyingcircusio/appenv.git
cd appenv

If you cloned the repo and want to create a new appenv project, you are in the wrong directory. Create a separate project directory and download appenv there instead.

Verification

Verify appenv is working:

./appenv version

Learn more about uv

appenv uses uv as its package manager — an extremely fast Python package and project manager written in Rust. If you’re new to uv:

Next Steps