Just Enough Python Packaging 🔗

Skip poetry. Skip pip. Do not pass go, jump directly to uv. It is without question the best way to manage python packages in 2026.

uv is an extremely fast Python package and project manager written in Rust. It replaces pip, pip-tools, venv, poetry, pyenv, and more. If you are still manually managing .venv folders or fighting with poetry lock times, it’s time to take some precious time back.

0. You need uv.
   Follow the official installation guide. You shouldn’t be installing Python any other way than through uv at this point.

1. Init the project.
   Use the --package flag. This sets up a standard src layout which is the industry standard.

uv init my-cool-project --package
cd my-cool-project

2. Project Layout
   Your project should look like this. This is the opinionated guidance that uv init gives you, and you should keep it!

my-cool-project/
├── pyproject.toml   # The brain of the project
├── uv.lock          # The source of truth (don't touch)
├── .python-version  # Managed for you
├── src/
│   └── my_package/  # Your actual code
│       └── __init__.py
└── tests/           # Where the tests live

3. Dependency Management
   Add what you need through command line.

uv add requests

You can also add this in the pyproject.toml. Make sure you uv sync!

4. Dev tools belong in dev groups.
   Don’t pollute your production dependencies with pytest or ruff. Use the --dev flag.

uv add --dev pytest ruff

5. Extras for the heavy stuff.
   If your package has “optional” features (like Excel support or a heavy UI), use extras.

uv add pandas --optional excel

This keeps the base install lightweight. It allows users the freedom to choose what parts of your package to install.

6. Run your code.
   Use uv run. It ensures you’re using the exact versions defined in your lockfile.

uv run python src/my_package/main.py

7. uvx is magic.
   This is the equivalent of npx for Node developers. It’s perfect for tools like Ruff. Ruff is so fast it makes other linters look like they’re from another century. It replaces Flake8, Black, and isort in one go.

uvx ruff check .

TODOs: 🔗

(Research these yourself!) 🔗

• uv Workspaces for when your project gets too big.
• Building and Publishing - uv build is all you need.
• Docker integration - How to stop building 2GB Python images.
• Ruff Configuration - Automate your formatting so you never have to think about it again.