smartrun 0.2.39

Run any Python script with automatic environment setup, fast package resolution via uv, and reproducible lockfile generation

smartrun

Run any Python script in a clean, disposable virtual environment — automatically.

smartrun 🚀

Run Python and Jupyter files with zero setup, zero pollution. Just run it. smartrun scans your script or notebook, detects the required third-party packages, creates (or reuses) an isolated environment, installs what’s missing — and runs your code. ✅ No more ModuleNotFoundError
✅ No more cluttered global site-packages
✅ Just clean, reproducible execution — every time

Features

• 🧪 Supports both .py and .ipynb files
• 🔍 Automatically detects and resolves imports
• 🛠️ Uses venv or fast uv environments (if available)
• 📦 Installs only what's needed, only when needed
• 💡 Reuses environments smartly to save time

---

Installation

🔹 Basic usage

pip install smartrun

This includes support for:

• Running standard Python scripts
• Automatic environment setup
• Fast dependency resolution with uv
• Reproducible installs via pip-tools 🔹 With Jupyter notebook support If you want to run .ipynb notebook files using smartrun, install the optional jupyter dependencies:

pip install "smartrun[jupyter]"

🔹 Development install (optional) For contributors and development work, install with:

pip install "smartrun[dev,jupyter]"

Requires Python 3.10+

---

Create an environment

✅ Create an environment : Windows / macOS / Linux

smartrun env .venv

✅ Activate the environment: Windows

 .venv\Scripts\activate

🐧 macOS/Linux

✅ Activate the environment: macOS/Linux ```bash source .venv/bin/activate ```

🪟 Windows

✅ Activate the environment: Windows ```bash .venv\Scripts\activate ```

Tip: smartrun will automatically create and manage a virtual environment if none is activated — but you're always free to bring your own. ✅ Run the script: Windows / macOS / Linux ```bash smartrun some_file.py ``` ✅ Run the jupyter file: Windows / macOS / Linux ```bash smartrun some_file.ipynb ```

Usage

smartrun your_script.py

Notebook

smartrun your_notebook.ipynb

Example file that we want to run

📄 some_file.py

# smartrun: numpy>=1.24 pandas>=2.0 rich>=13.0

import numpy as np
import pandas as pd
from rich import print

df = pd.DataFrame(np.random.randn(5, 3), columns=list("ABC"))
print("Data:")
print(df, end="\n\n")
print("Column means:")
print(df.mean())

✅ What SmartRun Does

Parses the comment for package names: numpy, pandas, rich

Creates or reuses a .venv

Installs any missing packages (via uv or pip)

Runs the script

No requirements.txt. No pip install. Just run the file.

Data Science Examples

🌸 Iris dataset analysis

```python # iris.py import seaborn as sns import pandas as pd import matplotlib.pyplot as plt # Load data df = sns.load_dataset('iris') # Show first few rows and summary print(df.head(), end="\n\n") print(df.describe(), end="\n\n") # Plot pairwise relationships sns.pairplot(df, hue='species') plt.savefig('iris_pairplot.png') ``` ```bash smartrun iris.py ```

🐼 Titanic Dataset demo

```python # titanic.ipynb import pandas as pd import seaborn as sns import matplotlib.pyplot as plt # Load dataset from GitHub url = 'https://raw.githubusercontent.com/datasciencedojo/datasets/master/titanic.csv' df = pd.read_csv(url) # Basic stats print(df[['Survived', 'Pclass', 'Sex']].groupby(['Pclass', 'Sex']).mean()) # Plot survival by class sns.countplot(data=df, x='Pclass', hue='Survived') plt.title('Survival Count by Passenger Class') plt.savefig('titanic_survival_by_class.png') print("Saved plot → titanic_survival_by_class.png") ``` ```bash smartrun titanic.ipynb ```

If the dependencies aren’t installed yet, `smartrun` will fetch them automatically. ## Why smartrun? Because setup should never block you from running great code. Whether you're experimenting, prototyping, or sharing — smartrun ensures your script runs smoothly, without dependency drama. ## Contributing Contributions are welcome! 🧑‍💻 If you’ve got ideas, bug fixes, or improvements — feel free to open an issue or a pull request. Let’s make smartrun even smarter together. ## License BSD 3‑Clause — see `LICENSE` for details. ---