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, if uv not installed, the native python will be used.
• 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 .venv after execution, if there was no venv created before.
• Cross-platform: Works on Unix-like systems and Windows.
• Simple UV wrapper: Can be used to run uv commands

Installation

make sure you have rust installed. uv is optional but recommended.

from source

1. Clone this repository:

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

2. Install the binary:

   cargo install --path .
   

from Github

cargo install --git https://github.com/guangyu-he/py_executer

from crates.io

cargo install py_executer

Usage

running python script

py_executer run <SCRIPT_PATH> [OPTIONS]

Arguments

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

Options

• -p, --project <PROJECT_PATH>: Specify the project directory (default: current directory).
• -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 if provided, it will be loaded. If a .env file is found under --project path, it will be loaded automatically
• --quiet: Suppress output from the CLI (python stdout and stderr will display normally).
• --clean: Clean the created uv-managed .venv and config files after execution. Pre-existing files are not deleted.
• -- <ARGs>: Arguments to pass to the Python script. Must be placed as the last argument(s) and after --.

running uv command

py_executer uv <COMMAND> [OPTIONS]

Example

minimum usage

assume there is a project like this:

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

py_executer run my_script.py

this will be equivalent to:

uv venv
uv pip install -r requirements.txt
# or uv sync --project xxx # if it is an uv project
export $(grep -v '^#' .env | xargs)  # if .env exists
PYTHONPATH=$PYTHONPATH:$(pwd)
uv run --project xxx my_script.py

or if no uv installed:

which python3
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
export $(grep -v '^#' .env | xargs)
PYTHONPATH=$PYTHONPATH:$(pwd)
python3 my_script.py

more customized options

py_executer run my_script.py --project /path/to/project -E DEBUG=true -- --input data.txt

this will be equivalent to:

uv venv --project /path/to/project # if venv is not created
uv pip install -r requirements.txt
# or uv sync --project /path/to/project # if it is an uv project
export $(grep -v '^#' /path/to/project.env | xargs)
PYTHONPATH=$PYTHONPATH:$(pwd)
DEBUG=true
uv run --project /path/to/project 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.

License

MIT