Set up a Python project

Most NJIA projects use Node and should start from the Innovation repository template. When you do need Python, use uv so the Python version, virtual environment, dependencies, and command-line tools are managed in one place.

Install uv

macOS

Install uv with Homebrew:

brew install uv

WSL and Linux

Install uv with Astral’s standalone installer:

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

If curl is not available, use wget:

wget -qO- https://astral.sh/uv/install.sh | sh

Restart your shell after the installer finishes so your PATH is updated.

Note

Astral’s official uv installation docs do not list apt as an installation method. For WSL and Linux, use the standalone installer unless a project has a specific reason to use another official method.

Native Windows

Install uv with WinGet:

winget install --id=astral-sh.uv -e

If WinGet is not available, use the official PowerShell installer:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify the installation

Confirm uv is available:

uv --version

Create a project

Create a new Python project and pin the Python version the project should use:

uv init my-python-project --python 3.14
cd my-python-project
uv sync

uv init creates a pyproject.toml for dependencies and a .python-version file for the project’s Python version. uv sync creates a .venv/ virtual environment and a uv.lock lockfile.

Commit pyproject.toml, .python-version, and uv.lock. Do not commit .venv/. If .venv/ is not already in .gitignore, add it.

Note

You usually do not need to activate the virtual environment manually. Run project commands through uv run and uv will use the project’s .venv/ automatically.

Add dependencies

Add runtime dependencies with uv add:

uv add requests

Add development-only tools with --dev:

uv add --dev pytest ruff

Run project code and tools with uv run:

uv run python main.py
uv run pytest
uv run ruff check .

Remove a dependency with uv remove:

uv remove requests

Work on an existing project

After cloning a Python project that already uses uv, install the locked dependencies:

uv sync

Then run the project through uv run:

uv run python main.py

If a tool specifically requires an activated virtual environment, activate the project environment after running uv sync:

source .venv/bin/activate

On native Windows PowerShell, use:

.venv\Scripts\activate

When you are done using an activated environment, exit it:

deactivate

Use Python tools without polluting projects

Install project dependencies into the project with uv add. Do not install project dependencies globally or into your system Python.

Caution

Global Python installs make one shared environment responsible for unrelated projects and tools. That can break projects when two dependencies need different versions, make setup hard to reproduce on another machine, and accidentally modify the Python installation your operating system or other tools rely on.

Use uv add for project dependencies and uvx or uv tool install for command-line tools. uv gives each project or tool its own managed environment, so tools stay available without leaking their dependencies into your projects.

For one-off command-line tools, use uvx:

uvx checkov --version

For tools you use often and want available on your PATH, use uv tool install:

uv tool install checkov
uv tool install ruff

If uv warns that its tool directory is not on your PATH, run uv tool update-shell and restart your shell.

uv keeps each installed tool in its own isolated environment, which avoids the dependency conflicts that happen when many tools are installed into one global Python environment.

Work with older requirements files

Some existing projects still use requirements.txt. You can install those dependencies into a local virtual environment with uv:

uv venv
uv pip install -r requirements.txt

For new Python projects, prefer pyproject.toml and uv.lock. To migrate dependencies from an existing requirements.txt file into a uv project, run:

uv add -r requirements.txt

Useful tools

• Black - Python counterpart to Biome/Prettier
• requests - HTTP library
• IPython - a better Python terminal (allows multi-line commands)

For data analysis:

• Pandas - lets you manipulate tables/csv equivalents in-memory. We’ve got a couple Pandas wizards at the office, so feel free to ask for help if you’re unfamiliar.
• Jupyter Notebooks - if you want to do iterative data analysis with charts/images as output, and you don’t care about source control (it sucks with git)
• Positron - RStudio, but for both Python and R. It’s a VSCode IDE fork that helps with doing iterative data analysis, including viewing charts + images as an output. Unlike Jupyter Notebooks, you’re still fundamentally writing a Python script and can keep that source controlled.

Frameworks you might want to consider

• Flask
• Django
• Streamlit