Common Workflows¶

Practical workflows for using appenv. See Locking Behavior for background on how appenv handles dependency locking.

When you have an existing project with requirements.txt and want to switch to appenv:

# If appenv is already in your project
./appenv migrate

# If not (e.g. running via uvx)
uvx appenv migrate

# After migration, verify and clean up
./http --help
rm requirements.txt

Version pins from requirements.txt are not preserved — uv.lock resolves fresh. Check the lockfile if exact versions matter.

See migrate for options and failure cases.

New Project from Scratch¶

mkdir myproject && cd myproject

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

If appenv is not yet on stable PyPI:

uvx --prerelease allow appenv init

The symlink http -> appenv runs the http binary from your installed dependencies. See Commands Reference for details on symlink dispatch.

ln -s appenv pytest
./pytest -xvs

Development Workflow¶

# Run the exposed binary (auto-prepares venv on first use)
./http

# Run dev tools — use uv run to include dev dependencies
uv run pytest -xvs
uv run ruff check .
uv run ruff format .

# Add dependencies
./appenv uv add --group dev pytest
./appenv update-lockfile

Adding and Upgrading Dependencies¶

# Add a production dependency (updates both pyproject.toml and uv.lock)
./appenv uv add requests

# Add a development dependency
./appenv uv add --group dev pytest

# Upgrade a specific package
./appenv uv lock --upgrade-package requests

# Upgrade all packages
./appenv uv lock --upgrade

CI/CD Integration¶

GitHub Actions¶

name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"

      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Run tests
        run: uv run pytest

./http auto-prepares the venv on first use — no explicit preparation step needed in CI.

Container Environments¶

In containers or on CIFS mounts, uv may warn about failed hardlinks:

warning: Failed to hardlink files; falling back to full copy.

This is harmless. To suppress it, set UV_LINK_MODE=copy:

UV_LINK_MODE=copy ./http

See astral-sh/uv#6101 for details.

Managing Multiple Python Versions¶

# pyproject.toml
[project]
requires-python = ">=3.11,<3.14"

appenv automatically selects the best available Python version. See Locking Behavior for details on UV universal resolution across the requires-python range.

Debugging Issues¶

Verbose Mode¶

APPENV_VERBOSE=1 ./http --version

Shows uv commands being executed, Python version selection, and venv creation steps.

Reset and Rebuild¶

./appenv reset

Python Version Selection¶

If the wrong Python version is selected, check:

requires-python in pyproject.toml — this is the constraint
PATH — appenv scans python3.X binaries newest-first
APPENV_BEST_PYTHON — set by appenv after selection, check with verbose mode

Override selection:

APPENV_BEST_PYTHON=/usr/bin/python3.12 ./mkdocs build

Working with Extras¶

# pyproject.toml
[project.optional-dependencies]
dev = ["pytest", "ruff"]

APPENV_EXTRAS=dev ./http

See self-update for the complete reference.