Skip to main content

​
Quick Setup

Get up and running with Windows Python Launcher in three simple steps:
1

Download the Launcher

Copy the PythonLauncher.bat file to your Python project’s root directory (where your main Python file and requirements.txt are located).
my-project/
├── PythonLauncher.bat  ← Place it here
├── main.py
├── requirements.txt
└── ...
2

Run the Launcher

Double-click PythonLauncher.bat to launch your project.The launcher will:
  • ✓ Detect your Python installation
  • ✓ Create a virtual environment (first run only)
  • ✓ Install dependencies from requirements.txt (first run only)
  • ✓ Run your Python script
3

Enjoy!

Your Python application is now running. Future runs will be faster since the environment is already set up.
The default configuration works for most projects. If your main file is named run.py, main.py, or app.py, the launcher will find it automatically.

​
Basic Usage Examples

​
Running Your Project

Simply double-click PythonLauncher.bat. The launcher searches for entry points in this order:
  1. run.py
  2. main.py
  3. app.py
The first file found will be executed.
# What happens automatically:
Python 3.11.0
Creating Virtual environment...
Installing dependencies...
Running main.py...
Drag any .py file onto PythonLauncher.bat to run that specific file.
my-project/
├── PythonLauncher.bat
├── main.py
├── test.py  ← Drag this onto the launcher
└── utils.py
Drag-and-drop is disabled when passarguments=1. Choose either argument passing or drag-and-drop functionality.
Enable argument passing to send parameters to your Python script:
PythonLauncher.bat
set passarguments=1
Then run from command prompt:
PythonLauncher.bat --config production --debug
Your Python script receives --config production --debug as arguments.

​
First Run Experience

On the first run, you’ll see output similar to this: 
Python 3.11.0
Creating Virtual environment...
Created virtual environment CPython3.11.0.final.0-64 in 2145ms
Installing dependencies...
Collecting flask>=2.0.0
Collecting requests>=2.28.0
  Using cached requests-2.31.0-py3-none-any.whl
Installing collected packages: flask, requests
Successfully installed flask-2.0.0 requests-2.31.0

# Your Python application starts here

​
Subsequent Runs

After the first run, startup is nearly instant: 
Python 3.11.0

# Your Python application starts immediately
The virtual environment and packages are already installed, so the launcher just activates the environment and runs your script.

​
Common Configuration

Edit PythonLauncher.bat to customize behavior. Here are the most common configurations: 
::----Configuration----::

::Python settings
set pythonversion=3.11
set pythondir=py

::Entry point detection
set initialfiles="run.py" "main.py" "app.py"

::Virtual environment
set usevenv=1
set venvname=pyvenv
set installrequirementsfile=1
set requirementsfile=requirements.txt

::Window behavior
set windowname=Python
set minimizedcmd=0
set autoclosecmd=0

::Argument handling
set passarguments=0

::Error handling
set alertifpynotinstalled=1

​
Configuration Reference

All configuration is done through variables at the top of PythonLauncher.bat:

​
Python Settings

VariableDefaultDescription
pythonversion3.11Python version to use with the py launcher. Ignored if pythondir is not py or py.exe
pythondirpyPath or command for Python executable. Use %cd%\path\to\python.exe for relative paths
The py launcher is the recommended option. It comes with Python 3.3+ and handles version selection automatically.

​
Entry Point Detection

VariableDefaultDescription
initialfiles"run.py" "main.py" "app.py"List of files to search for. First match is executed. Follow the quote structure to add more
Example: To prioritize server.py, then app.py: 
set initialfiles="server.py" "app.py" "main.py"

​
Virtual Environment

VariableDefaultDescription
usevenv1Create and use a virtual environment (1 = enabled, 0 = disabled)
venvnamepyvenvName of the virtual environment directory
installrequirementsfile1Install requirements.txt when creating venv (1 = enabled, 0 = disabled)
requirementsfilerequirements.txtPath to the requirements file
Dependencies are only installed when the virtual environment is first created. To update packages, delete the venv folder (e.g., pyvenv) and run the launcher again.

​
Window Behavior

VariableDefaultDescription
windownamePythonTitle displayed in the command prompt window
minimizedcmd0Start command prompt minimized (1 = yes, 0 = no)
autoclosecmd0Close window when Python script finishes (1 = yes, 0 = no)

​
Advanced Options

VariableDefaultDescription
passarguments0Pass command-line arguments to Python script (1 = yes, 0 = no). Disables drag-and-drop!
alertifpynotinstalled1Alert and open Python download page if not installed (1 = yes, 0 = no)

​
Troubleshooting

Symptom: Launcher exits immediately or shows “Python is not recognized”Solution:
  1. Check if Python is installed: Open Command Prompt and run py -V
  2. If not installed, run the launcher with alertifpynotinstalled=1 to automatically open the download page
  3. Alternatively, download Python from python.org/downloads
  4. During installation, check “Add Python to PATH”
Symptom: The launcher uses a different Python version than expectedSolution: Update the pythonversion variable:
set pythonversion=3.11
set pythondir=py
Verify available versions:
py --list
Symptom: Dependencies aren’t updating after modifying requirements.txtSolution: The launcher only installs dependencies when creating the venv. To update:
  1. Delete the virtual environment folder (default: pyvenv)
  2. Run the launcher again to recreate it with new dependencies
# From command prompt in your project directory
rmdir /s /q pyvenv
PythonLauncher.bat
Symptom: Launcher opens a Python shell instead of running your scriptSolution: Your main file name doesn’t match the default list. Either:
  1. Rename your file to run.py, main.py, or app.py
  2. Update initialfiles in the launcher:
# If your main file is named server.py
set initialfiles="server.py" "run.py" "main.py" "app.py"
Symptom: Dragging a .py file onto the launcher doesn’t run itSolution: Check if argument passing is enabled:
set passarguments=0  # Must be 0 for drag-and-drop to work
You can’t use both features simultaneously. Choose one based on your needs.

​
Next Steps

Configuration Guide

Learn about all configuration options in detail

Examples

See real-world usage examples and templates

Usage Guide

Learn different ways to run your Python scripts

Troubleshooting

Solutions to common problems
Need Help? Check the Introduction for an overview of features, or dive into the Configuration Guide for detailed customization options.