py-trkpac 0.4.0

Global Python package manager with SQLite tracking

py-trkpac

A global Python package manager for linux that wraps pip with SQLite tracking. Install packages into a single shared directory, accessible from any terminal without activating a venv.

Why

Python's default tooling pushes you toward virtual environments for everything. That's fine for project-specific dependencies, but for packages you use everywhere (pytest, requests, httpx, etc.), you end up with dozens of venvs all containing the same libraries.

py-trkpac gives you a single managed directory for globally available Python packages. It:

• Installs packages via pip into one target directory
• Tracks every package and its dependencies in SQLite
• Enforces one version per package (no silent duplicates)
• Detects dependency conflicts before they happen
• Manages your shell config (PATH/PYTHONPATH) automatically
• Works on Ubuntu without fighting PEP 668 (externally-managed-environment)

You still use venvs for project-specific needs. py-trkpac handles the rest.

Install

Requires Python 3.13+. No external dependencies — uses only Python stdlib.

From PyPI

pip install py-trkpac
py-trkpac init

From PyPI (venv bootstrap)

On systems with PEP 668 (externally-managed-environment), use a temporary venv to bootstrap py-trkpac into its own managed directory:

# Create a temporary venv and install py-trkpac
python3 -m venv /tmp/trkpac-bootstrap
/tmp/trkpac-bootstrap/bin/pip install py-trkpac

# Initialize (sets up target directory, DB, and shell config)
/tmp/trkpac-bootstrap/bin/py-trkpac init

# Install py-trkpac into its own managed directory
/tmp/trkpac-bootstrap/bin/py-trkpac install py-trkpac

# Open a new terminal — py-trkpac is now on your PATH via the managed directory
# You can safely remove the bootstrap venv
rm -rf /tmp/trkpac-bootstrap

From source (development)

git clone https://github.com/aryanduntley/py-trkpac.git
ln -s /path/to/py-trkpac/py-trkpac ~/.local/bin/py-trkpac
py-trkpac init

Usage

Initialize

py-trkpac init
py-trkpac init --target ~/my-python-libs
py-trkpac init --shell-config ~/.zshrc

Sets the target directory where packages will be installed. Creates the SQLite database and adds PATH/PYTHONPATH entries to your shell config using managed marker comments.

Install packages

py-trkpac install requests httpx pytest

• Checks the database for existing packages before installing
• Warns if a package is already installed in system Python (/usr/lib/python3/dist-packages/) and asks before shadowing it
• Prompts on version conflicts or when a package is already installed as a dependency
• Runs pip with --target and --upgrade
• Records all installed packages and auto-detected dependencies in the database
• Only updates the database after pip reports success

Install local projects

py-trkpac install /path/to/downloaded-project
py-trkpac install ~/Desktop/Projects/my-mcp-server

• Detects local directories with pyproject.toml or setup.py
• Installs via pip into the same target directory as PyPI packages
• Parses pyproject.toml to identify the package name and track it in the database
• Tracks the source path so you know where each local package came from
• Shows as "local" type in py-trkpac list
• To update after source changes, just re-run the install command

Remove packages

py-trkpac remove selenium

• Warns if other packages depend on the one being removed
• Cleans up files using pip's RECORD manifest
• Prompts to remove orphaned dependencies that nothing else needs, recursively through the full dependency tree

List packages

py-trkpac list

Package          Version      Type        Installed
---------------  -----------  ----------  ----------
aifp             0.1.0        local       2026-02-07
click            8.3.1        explicit    2026-02-07
cryptography     46.0.4       explicit    2026-02-07
certifi          2026.1.4     dependency  2026-02-07
cffi             2.0.0        dependency  2026-02-07
...

63 package(s): 17 explicit, 1 local, 45 dependencies

List dependencies

py-trkpac list-deps pytest

pytest==9.0.2 depends on:
  packaging==26.0
  iniconfig==2.3.0
  pluggy==1.6.0

Required by:
  pytest-cov==7.0.0

Update packages

py-trkpac update           # update all explicit packages
py-trkpac update requests  # update a specific package

Rebuild after a Python upgrade

py-trkpac rebuild

Reinstalls every tracked package — explicit and local — for the Python interpreter you are running now. Use this after an OS upgrade bumps your system Python to a new minor version (e.g. 3.13 → 3.14). It prunes the stale, ABI-incompatible compiled extensions, reinstalls explicit packages (pip re-resolves their dependencies), and reinstalls local packages from their tracked source paths.

View/change config

py-trkpac config
py-trkpac config set target_path /new/path

Surviving Python upgrades

A Python minor-version upgrade (3.13 → 3.14) is the one event that can break a global package directory. Compiled (C-extension) packages — numpy, cryptography, pydantic-core, lxml, etc. — ship .so files locked to the exact CPython minor version they were built for. When your OS replaces the interpreter, every one of them stops importing. This is fundamental to CPython and affects pip, venv, pipx, and conda equally; the only real fix is to reinstall them for the new interpreter.

py-trkpac is built to make this a known, one-command recovery rather than a cryptic failure:

• It tells you. py-trkpac records the Python version your packages were installed under. If you run any command under a different interpreter, it prints a prominent warning naming the old and new versions and pointing you at the fix. (Databases created before this feature are detected automatically by inspecting installed binaries.)
• It fixes it in one command. py-trkpac rebuild reinstalls everything for the current Python and prunes the dead binaries.
• The tool itself never breaks. py-trkpac is pure standard library, so it has no compiled parts to invalidate. py-trkpac init installs a launcher that delegates to whatever python3 is current (rather than pip's version-pinned console_scripts stub). Combined with self-installing py-trkpac into its own managed directory (py-trkpac install py-trkpac), the CLI keeps working across upgrades with zero intervention — only the managed packages need a rebuild.

Tip: install py-trkpac into its own managed directory so it benefits from the resilient launcher. The PyPI bootstrap recipe above already does this.

How it works

Architecture

py-trkpac is a policy layer on top of pip. pip does all the real work (dependency resolution, downloading, building, installing). py-trkpac decides:

• Whether to install (conflict detection)
• Where to install (target directory)
• What to record (database tracking)
• When to prompt (user-facing decisions)

Database

SQLite database stored at <target_path>/.py-trkpac.db with three tables:

• config — key/value settings (target path, shell config path)
• packages — every installed package (name, version, explicit vs dependency, dates)
• package_dependencies — many-to-many join table tracking which packages depend on which

Dependencies are packages too. numpy as a dependency of torch is a row in packages with is_explicit=0, linked via package_dependencies.

Shell config management

py-trkpac manages a block in your shell config using marker comments:

# >>> py-trkpac managed >>>
export PATH="$HOME/python-libraries/bin:$PATH"
export PYTHONPATH="$HOME/python-libraries${PYTHONPATH:+:$PYTHONPATH}"
# <<< py-trkpac managed <<<

This block is added, updated, or removed idempotently. A backup of your shell config is created before the first modification.

Package removal

Since pip uninstall doesn't work with --target installs, py-trkpac handles removal directly by parsing the RECORD file in each package's .dist-info directory and deleting the listed files.

Project structure

py-trkpac/
├── py-trkpac                 # shell script entry point
├── src/
│   └── py_trkpac/
│       ├── __init__.py       # version
│       ├── __main__.py       # python -m py_trkpac
│       ├── cli.py            # argparse, command dispatch
│       ├── db.py             # SQLite schema and operations
│       ├── installer.py      # pip wrapper, metadata parsing, rebuild
│       ├── shell.py          # .bashrc management + resilient launcher
│       ├── health.py         # Python-version tracking, upgrade warning
│       └── utils.py          # name normalization, prompts
├── shell_configs/            # future OS support stubs
│   ├── bashrc.py
│   ├── zshrc.py
│   └── fish.py
├── pyproject.toml
└── .gitignore

License

MIT