The Windows Python Launcher can automatically detect and run Python files in your project directory without requiring you to specify which file to run. This is controlled by the initialfiles configuration.
Default Initial Files
By default, the launcher looks for these files in order:
set initialfiles="run.py" "main.py" "app.py"
Searches for first file
Checks if run.py exists in the current directory
Searches for second file
If run.py doesn’t exist, checks for main.py
Searches for third file
If main.py doesn’t exist, checks for app.py
Runs the first match
Executes the first file found and stops searching
Fallback to Python shell
If no files are found, opens an interactive Python shell
The launcher only runs one file - the first one it finds. The order in the initialfiles list determines the priority.
How It Works
Code Implementation
From PythonLauncher.bat:137-157:
rem Check if any initial file exists.
set foundFile=
for %%f in (%initialfiles%) do (
if exist %%~f (
set foundFile=%%~f
set command=start %min% "%windowname%" cmd /k "!venvcmd! & %pythondir% %pycmd% !foundFile! %minexit%"
goto :runFile
)
)
rem No initial file found - open Python shell
set command=start %min% "%windowname%" cmd /k "!venvcmd! & %pythondir% %pycmd%"
goto :runFile
- Loops through each filename in
initialfiles
- Checks if the file exists using
if exist
- Sets the command to run the first file found
- Immediately jumps to
:runFile (stops searching)
- If no files exist, opens a Python shell
Customizing Initial Files
You can customize the list to match your project structure.
Adding Custom Files
Example 1: Web application
set initialfiles="app.py" "wsgi.py" "main.py" "run.py"
app.py (common for Flask/FastAPI apps) before checking other files.
Example 2: Django project
set initialfiles="manage.py" "run.py" "main.py"
set initialfiles="analyze.py" "process.py" "main.py"
set initialfiles="start.py" "launcher.py" "init.py" "main.py"
Changing the Order
The order matters! The first file found will be executed:
# If both run.py and main.py exist, run.py will be executed
set initialfiles="run.py" "main.py" "app.py"
# If both run.py and main.py exist, main.py will be executed
set initialfiles="main.py" "run.py" "app.py"
Put your most common entry point first to ensure it runs when multiple initial files exist.
Single Entry Point
If your project only has one entry point:
set initialfiles="run.py"
run.py and open a Python shell if it doesn’t exist.
Files in Subdirectories
The initialfiles configuration only checks the current directory (where the launcher is located). It does not search subdirectories.
set initialfiles="src\main.py" "app\run.py" "main.py"
project/
├── PythonLauncher.bat
├── src/
│ └── main.py ← Will be found and executed
└── requirements.txt
Use Cases
Multi-Purpose Project
You have a project with different entry points for different purposes:
project/
├── PythonLauncher.bat
├── server.py # Web server
├── worker.py # Background worker
├── migrate.py # Database migration
└── main.py # Default CLI tool
set initialfiles="main.py" "server.py" "worker.py"
main.py by default. Use drag and drop to run other files.
Development vs Production
Create different launchers for different environments:
PythonLauncher-Dev.bat:
set initialfiles="dev.py" "main.py"
set windowname=Development
set initialfiles="prod.py" "main.py"
set windowname=Production
Testing Environment
Create a test launcher:
set initialfiles="test_runner.py" "pytest_run.py" "main.py"
set windowname=Test Runner
No Initial Files Found
If none of the initial files exist, the launcher opens an interactive Python shell:
C:\Projects\MyApp> py -3.11
Python 3.11.5 (tags/v3.11.5:cce6ba9, Aug 24 2023, 14:38:34) [MSC v.1936 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>
Virtual Environment Activation
Even without initial files, the Python shell runs in your virtual environment (if usevenv=1):
C:\Projects\MyApp> pyvenv\Scripts\activate
(pyvenv) C:\Projects\MyApp> py -3.11
Python 3.11.5 ...
>>> import requests # Packages from venv are available
>>>
- Testing installed packages interactively
- Running quick Python commands
- Debugging environment issues
Best Practices
1. Include Standard Names
Always include common entry point names:
set initialfiles="run.py" "main.py" "app.py"
2. Put Project-Specific Files First
If your project uses a specific entry point, list it first:
# For a Flask app
set initialfiles="wsgi.py" "app.py" "main.py"
# For a Django project
set initialfiles="manage.py" "main.py"
# For a custom script
set initialfiles="launcher.py" "main.py" "run.py"
3. Document Your Entry Points
Create a README or comment in your batch file:
# Entry points:
# - server.py: Starts the web server
# - worker.py: Starts background tasks
# - main.py: CLI interface
set initialfiles="server.py" "main.py"
4. Limit the List
Don’t add too many files. Keep it to 3-5 most likely entry points:
# Good: Clear and focused
set initialfiles="run.py" "main.py" "app.py"
# Too many: Unclear which is primary
set initialfiles="run.py" "main.py" "app.py" "start.py" "launch.py" "init.py" "server.py"
Integration with Other Features
With passarguments=1
When passarguments=1, the launcher finds the first initial file and passes all arguments to it:
set passarguments=1
set initialfiles="run.py" "main.py"
PythonLauncher.bat --debug --config prod
py -3.11 run.py --debug --config prod
With Drag and Drop
When you drag a file onto the launcher (with passarguments=0), the initial files list is ignored:
set passarguments=0
set initialfiles="run.py" "main.py"
test.py onto the launcher will run test.py, not run.py or main.py.
See Drag and Drop for more details.
With Virtual Environment
Initial files are always executed in the configured virtual environment:
set usevenv=1
set venvname=pyvenv
set initialfiles="run.py" "main.py"
# 1. Create venv if needed
py -3.11 -m venv pyvenv
# 2. Install requirements if needed
pyvenv\Scripts\activate
py -3.11 -m pip install -r requirements.txt
# 3. Run initial file in venv
call pyvenv\Scripts\activate
py -3.11 run.py
Examples by Project Type
Flask Application
set initialfiles="wsgi.py" "app.py" "run.py" "main.py"
set windowname=Flask Server
flask-app/
├── PythonLauncher.bat
├── wsgi.py ← Runs first
├── app.py
├── requirements.txt
└── pyvenv/
FastAPI Application
set initialfiles="main.py" "app.py" "run.py"
set windowname=FastAPI Server
Data Analysis Project
set initialfiles="analyze.py" "process.py" "explore.py" "main.py"
set windowname=Data Analysis
Automation Scripts
set initialfiles="automate.py" "scheduler.py" "main.py"
set windowname=Automation
Testing Framework
set initialfiles="run_tests.py" "pytest_runner.py" "test_all.py"
set windowname=Test Runner
Troubleshooting
Wrong File Runs
If the wrong file is being executed, check the order:
# Current configuration
set initialfiles="main.py" "run.py" "app.py"
# If you want run.py to run instead, reorder:
set initialfiles="run.py" "main.py" "app.py"
File Not Found
If your file exists but isn’t found:
-
Check the filename exactly (case matters on some systems):
# If your file is Run.py (capital R)
set initialfiles="Run.py" "main.py"
-
Check the file location (must be in same directory as launcher):
project/
├── PythonLauncher.bat ← Here
└── run.py ← Must be here too
-
Check for typos:
# Wrong
set initialfiles="runn.py" "main.py"
# Correct
set initialfiles="run.py" "main.py"
Always Opens Python Shell
If the launcher always opens a Python shell:
- None of your initial files exist
- The filenames are misspelled
- The files are in a subdirectory (need to include path)
Solution:
# Add the correct path
set initialfiles="src\run.py" "run.py" "main.py"
To debug, open a command prompt in your project directory and run dir *.py to see all Python files.
Quick Reference
| Configuration | Behavior |
|---|
set initialfiles="run.py" "main.py" | Runs run.py if it exists, otherwise main.py |
set initialfiles="app.py" | Only runs app.py, no fallback |
set initialfiles="src\main.py" "main.py" | Checks src\main.py first, then root main.py |
| Empty list or no files found | Opens Python interactive shell |
With passarguments=1 | Passes arguments to the initial file |
| With drag and drop | Ignores initial files, runs dragged file |