How to Run a Raspberry Pi Program on Startup

Contributors: Shawn Hymel
Favorited Favorite 21

Method 2: autostart

If you need access to elements from the X Window System (e.g. you are making a graphical dashboard or game), then you will need to wait for the X server to finish initializing before running your code. One way to accomplish this is to use the autostart system.

Note: Raspbian is based on the LXDE desktop environment. As a result, the location of the autostart script might be different depending on your particular Linux computer and distribution version.

After your desktop environment starts (LXDE-pi, in this case), it runs whatever commands it finds in the profile's autostart script, which is located at /home/pi/.config/lxsession/LXDE-pi/autostart for our Raspberry Pi. Note that the directory pi might be different if you created a new user for your Raspberry Pi. If no user autostart script is found, Linux will run the global /etc/xdg/lxsession/LXDE-pi/autostart script instead.

In addition to running commands in autostart, Linux will also look for and execute .desktop scripts found in /home/pi/.config/autostart. The easiest way to execute GUI programs on boot is to create one of these .desktop scripts.

Create a .desktop File

You do not need root-level access to modify your profile's (user's) autostart and .desktop files. In fact, it is recommended that you do not use sudo, as you may affect the permissions of the file (e.g. the file would be owned by root) and make them unable to be executed by autostart (which has user-level permissions).

Open a terminal, and execute the following commands to create an autostart directory (if one does not already exist) and edit a .desktop file for our clock example:

mkdir /home/pi/.config/autostart
nano /home/pi/.config/autostart/clock.desktop

Copy in the following text into the clock.desktop file. Feel free to change the Name and Exec variables to your particular application.

[Desktop Entry]
Exec=/usr/bin/python3 /home/pi/
Note: We are calling python3 explicitly here to prevent any confusion about which Python version to use.

.desktop file for running a Python script on boot

Save and exit with ctrl + x, followed by y when prompted to save, and then enter. Reboot with:

sudo reboot

When your Raspberry Pi starts up, make sure to log in to the desktop (if it does not do so automatically). Your script should start running right away!


Nothing Happens

If your script does not run as soon as you see the desktop, there could be several issues. First, make sure that you have logged in (autostart does not start until you have logged in). You could also try enabling auto-login in raspi-config. Second, make sure you are using absolute directory names (e.g. /home/pi/ Third, try following some of the suggestions below to enable stdout and stderr to see what's going on.

Use a Specific Version of Python

As it turns out, autostart runs before .bashrc, so the command python still refers to Python 2. To explicitly call Python 3, we should change our command in autostart to:

@/usr/bin/python3 /home/pi/


Unfortunately, running a program from autostart makes it difficult to output or log to a file, and lxterminal (the default terminal program in Raspbian) is too simplistic to help us here. To get some kind of logging, we'll need to use a different terminal program (we'll use xterm). Open a terminal and enter the following command

sudo apt-get install xterm -y

In your .desktop file, change your Exec command to the following:

Exec=xterm -hold -e '/usr/bin/python3 /home/pi/'

Restart your Raspberry Pi. Now, after you log into your desktop, you should see a new terminal window open followed by your program running. If you stop your program (exiting out of it, pressing ctrl + c in the xterm window, or killing the process as detailed below), the xterm window will stay open, allowing you to read all of the output and error statments from your program.

How to Stop Your Program

If your program is running in the background, there might be no obvious way of halting it. You can always delete your .desktop files and restart, but that might take a while. A better option might be to kill the process associated with your program. In a terminal, enter the following:

sudo ps -ax | grep python

ps -ax tells Linux to list out all the currently processes. We send that output to grep, which allows us to search for keywords. Here, we're looking for python, but feel free to change it to the name of your program. Find the process ID (PID) number to the left of the listed process, and use the kill command to terminate that process:

sudo kill <PID>
Heads up! Make sure you type the PID correctly! If you kill the wrong process, you could halt Linux, and you would need to reboot again.

Terminating a process with the kill command

If you are using the example, you should see the application quit out.

How to Stop Your Program from Running on Boot

To prevent your program from running on boot, you just need to delete the .desktop file. In a terminal, enter the command (replacing clock.desktop with the name of your particular .desktop file):

rm /home/pi/.config/autostart/clock.desktop

Reboot your Pi, and your program should no longer run on startup.