py_executer

A Rust-based command-line tool to execute Python scripts with automatic virtual environment and dependency management. py_executer streamlines running Python code by handling environment setup, dependency installation, and environment variables, making your workflow faster and more reliable.

Features

• Automatic Virtual Environment Management: Manage a Python virtual environment using uv.
• Dependency Installation: Installs dependencies from requirements.txt automatically.
• .env File Support: Loads environment variables from a .env file or from CLI.
• Setup PYTHONVENV: Automatically set python path based on the path where the CLI is executed.
• Custom Environment Variables: Pass additional environment variables via CLI.
• Flexible Python Arguments: Pass extra arguments to the Python script.
• Clean Mode: Clean the created uv-managed .venv and config files after execution, sensorless to execute a python script.
• Cross-platform: Works on Unix-like systems and Windows.

Installation

1. Install Rust and Cargo.
2. Clone this repository:

   git clone https://github.com/guangyu-he/py_executer
   cd py_executer
   

3. Build the project:

   cargo build --release
   

4. Or simply install the binary:

    cargo install --path .

5. (Optional) Install uv if not already present. The tool will give a hint to install it if uv is essential to be called.

Usage

py_executer <SCRIPT_PATH> [OPTIONS]

Arguments

• <SCRIPT_PATH>: Path to the Python script to execute.

Options

• -v, --venv <VENV_PATH>: Specify a custom virtual environment path (default: .venv or venv). If a valid venv is present, this venv will be used directly (not managed by uv), requirements.txt will not be installed, and clean mode will be ignored.
• -E, --env <KEY=VALUE>: Additional environment variables in the format KEY=VALUE. Can be used multiple times.
• -e, --env-file <ENV_FILE>: Path to a .env file (default: .env in the current directory).
• --quiet: Suppress output from the CLI.
• --clean: Clean the created uv-managed .venv and config files after execution. Pre-existing files are not deleted.
• -A, --py-arg <ARGs>: Additional arguments to pass to the Python script. Must be placed as the last argument(s) and will be passed directly to Python.

Example

minimum usage

assume there is a project like this:

project/
├── myscript.py
├── requirements.txt
└── .env

py_executer my_script.py

this will be equivalent to:

uv init --bare
uv venv
uv add -r requirements.txt
export $(grep -v '^#' .env | xargs)  # if .env exists
PYTHONPATH=$PYTHONPATH:$(pwd)
.venv/bin/python my_script.py

after the execution, the script will create uv project files

project/
├── myscript.py
├── requirements.txt
├── .env
├── uv.lock
├── .venv/
└── pyproject.toml

to clean up generated files afterward, you can add --clean in the argument

more customized options

py_executer my_script.py -v venv -E DEBUG=true -A --input data.txt

this will be equivalent to:

export $(grep -v '^#' .env | xargs)
PYTHONPATH=$PYTHONPATH:$(pwd)
DEBUG=true
venv/bin/python3 my_script.py --input data.txt

Project Structure

• src/main.rs: Main CLI logic and environment setup.
• src/lib/: Internal modules for utilities, macros, and uv integration.

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.