Metadata-Version: 2.4
Name: appenv
Version: 2026.5.18a3
Summary: Self-contained bootstrapping/updating of Python applications deployed through shared repositories.
Project-URL: Homepage, https://github.com/flyingcircusio/appenv/
Project-URL: Issues, https://github.com/flyingcircusio/appenv/issues
Project-URL: Repository, https://github.com/flyingcircusio/appenv.git
Author-email: Christian Theune <ct@flyingcircus.io>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: deployment
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# appenv

appenv pins Python packages to exact versions and exposes their binaries
via symlinks — one file, no installation step. Drop it into a repository,
commit it, and every checkout (local or remote) gets the same tools at the
same versions by running `./http`, `./pytest`, `./batou`, or whatever you need.

**appenv never modifies your system** — all state lives in `.appenv/` inside
the project directory. Remove that folder and nothing is left behind.

## Using an existing appenv project

Someone gave you a project that already uses appenv? Just run the command:

```console
git clone <project> && cd <project>
./http  # First run sets up everything automatically
```

Running the command will get an appenv-managed [uv](https://docs.astral.sh/uv/) if it's not globally available on your system.

No `uv.lock` (should be committed) or dependencies changed?

```console
./appenv update-lockfile
```

(Only needed again after manually editing `pyproject.toml`)

Use `./appenv uv add/remove` to manage your dependencies or just use `uv` as you are used to it.


### Upgrading from requirements.txt

Already an appenv user and still using `requirements.txt` instead of `pyproject.toml`?

```console
uvx appenv migrate
```

## New Project

Requires Python 3.9+ (managed environments need 3.10+). [uv](https://docs.astral.sh/uv/) 0.5.0+ is auto-installed if not found.
Get appenv via `uvx` or download the single-file script.

`appenv init` will ask you some questions and set up the project. The example
assumes that you want to run a binary called `http` from the `httpie` package.

### uvx (uv)

`uvx` is part of [uv](https://docs.astral.sh/uv/) — the easiest way to start:

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

### Manual Download

No uv installed? Download appenv directly:

```shell
curl -sL https://raw.githubusercontent.com/flyingcircusio/appenv/master/src/appenv.py -o appenv
chmod +x appenv
# appenv init is interactive
# Answer:
# httpie as dependency
# http as binary
./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 (from the [httpie](https://github.com/httpie/httpie) package)

The repository now contains:

```shell
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)
```

### Development

For dev tooling, `uv run` and other `uv` commands work transparently.
`appenv` automatically creates a `.venv` symlink to make this work:

```shell
# includes dev dependencies automatically
uv run pytest -xvs
```

## Documentation

Full documentation at [Readthedocs](https://appenv-test.readthedocs.io):

- [Installation](docs/user/installation.md) -- how to get appenv
- [Commands Reference](docs/user/commands.md) -- all commands with options
- [Workflows](docs/user/workflows.md) -- common usage patterns
- [Locking Behavior](docs/user/locking-behavior.md) -- how uv.lock works
- [Developer Guide](docs/dev/index.md) -- development setup and architecture
