In this lesson, you will learn how to sync your local source code with your virtual environment so that any changes you make are immediately reflected in your project without needing a re-installation.
The Problem with Standard Installs
When you run pip install . inside your project directory, Python copies your package into the site-packages folder of your virtual environment. If you modify a file in your project, the installed version remains unchanged. To see your updates, you would have to run the install command again, which is inefficient and slows down your development cycle.
The Solution: Editable Mode
Editable installs bridge this gap. By using the "editable" flag, Python creates a symbolic link (or a .pth file) in your virtual environment that points directly to your source directory. Instead of copying your code, the environment "looks" at your active development folder.
To perform an editable install, use the -e flag with your package manager:
# Using pip
pip install -e .
# Using uv
uv pip install -e .
Why Use This?
- Instant Feedback: Any changes you save to your
.pyfiles are immediately available to any script or test suite running in that environment. - Simplified Debugging: If you have a separate project (like an integration test suite) that imports your package, it will always use the latest version of your code, ensuring that you are debugging exactly what you are currently writing.
- Clean Workflow: You don’t need to repeatedly package, build, or reinstall while working on your core logic.
Best Practice: The Src-Layout
Since you are already using the src-layout pattern, your pyproject.toml should define your package structure so that the editable install can correctly map your src/ folder to the importable module. When you run pip install -e ., your package becomes importable from anywhere in the terminal, while remaining tethered to your local file system.
Key Takeaway: Editable installs allow you to develop your code locally while keeping your environment seamlessly synced, eliminating the need to reinstall your package every time you save a change.