Installation using pip¶
This is a guide to installing WeeWX using pip, the
Preferred Installer Program for Python. It can be used on almost any
operating system that offers Python v3.6 or greater. Python 2, or earlier
versions of Python 3, will not work.
Although you do not need root privileges to install and configure WeeWX using
pip, you will need them to set up a daemon, and you may need them to change
device permissions.
Install pip and venv¶
While there are many ways to install WeeWX using pip (see the wiki document
pip install strategies
for a partial list), we recommend creating a Python virtual environment,
because it is the least likely to disturb the rest of your system. It is
worth reading about venv,
the module used to create a virtual environment, in the Python3 documentation.
To ensure that your Python has both pip and venv, follow the instructions
below for your system. For details, see the document Installing pip with
Linux Package Managers.
sudo apt update
sudo apt install python3-pip -y
sudo apt install python3-venv -y
sudo yum update
sudo yum install python3-importlib-resources
sudo yum install python3-pip -y
sudo yum install python3-venv -y
sudo yum update
sudo yum install python3-pip -y
sudo zypper refresh
sudo zypper install python3-importlib_resources
sudo zypper install python3-pip -y
sudo zypper install python3-venv -y
sudo pkg install py39-pip
sudo pkg install py39-sqlite3
sudo pkg install py39-Pillow
On BSD systems, it is easier to use the packaged py39-Pillow than it is to do a pip install of Pillow into a virtual environment, since the latter requires many other development packages
# There is no step 1!
# The python3 included with macOS already has pip and venv installed
Install in a virtual environment¶
To install WeeWX in a virtual environment, follow the directions below.
# Create the virtual environment
python3 -m venv ~/weewx-venv
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment
python3 -m pip install weewx
When you are finished, the WeeWX executables and dependencies will have been installed inside the virtual environment.
If you have any problems, see the wiki article Troubleshooting pip installs for help.
Provision a new station¶
While the instructions above install WeeWX, they do not set up the
configuration specific to your station, nor do they set up the reporting
skins. That is the job of the tool weectl.
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Create the station data
weectl station create
The tool weectl will ask you a series of questions, then create a directory
weewx-data in your home directory with a new configuration file, skins,
utility files, and examples. The database and reports will also go into that
directory, but only after you run weewxd, as shown in the following step.
Run weewxd¶
The program weewxd does the data collection, archiving, uploading, and
report generation. You can run it directly, or as a daemon.
Run directly¶
When you run WeeWX directly, it will print data to the screen. WeeWX will
stop when you log out, or when you terminate it with control-c.
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Run weewxd
weewxd
Run as a daemon¶
To make WeeWX start when the system is booted, you will want to run weewxd
as a daemon. Run the daemon setup script to configure your system. This script
installs the startup/shutdown configuration appropriate to your operating
system. You will need root privileges to do this.
sudo sh ~/weewx-data/scripts/setup-daemon.sh
Then follow the directions below to start weewxd as a daemon.
# For Linux systems that use systemd, e.g., Debian, Redhat, and SUSE.
sudo systemctl start weewx
# For Linux systems that use SysV init, e.g., Slackware, Devuan, and Puppy.
sudo /etc/init.d/weewx start
# For BSD systems, e.g., FreeBSD and OpenBSD.
sudo service weewx start
# For macOS systems.
sudo launchctl load /Library/LaunchDaemons/com.weewx.weewxd.plist
Verify¶
After about 5 minutes (the exact length of time depends on your archive interval), copy the following and paste into a web browser. You should see your station information and data.
~/weewx-data/public_html/index.html
Note
Not all browsers understand the tilde ("~") mark. You may
have to substitute an explicit path to your home directory,
for example, file:///home/jackhandy instead of ~.
If you have problems, check the system log. See the Troubleshooting section of the User's guide for more help.
Configure¶
If you chose the simulator as your station type, then at some point you will probably want to switch to using real hardware. This is how to reconfigure.
# Stop the weewx daemon:
sudo systemctl stop weewx
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Reconfigure to use your hardware
weectl station reconfigure
# Remove the old database
rm ~/weewx-data/archive/weewx.sdb
# Start the weewx daemon
sudo systemctl start weewx
# Stop the weewx daemon:
sudo /etc/init.d/weewx stop
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Reconfigure to use your hardware
weectl station reconfigure
# Remove the old database
rm ~/weewx-data/archive/weewx.sdb
# Start the weewx daemon
sudo /etc/init.d/weewx start
# Stop the weewx daemon:
sudo service weewx stop
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Reconfigure to use your hardware
weectl station reconfigure
# Remove the old database
rm ~/weewx-data/archive/weewx.sdb
# Start the weewx daemon
sudo service weewx start
# Stop the weewx daemon:
sudo launchctl unload /Library/LaunchDaemons/com.weewx.weewxd.plist
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Reconfigure to use your hardware
weectl station reconfigure
# Remove the old database
rm ~/weewx-data/archive/weewx.sdb
# Start the weewx daemon
sudo launchctl load /Library/LaunchDaemons/com.weewx.weewxd.plist
Customize¶
To enable uploads, or to enable other reports, modify the configuration file
~/weewx-data/weewx.conf using any text editor such as nano:
nano ~/weewx-data/weewx.conf
The reference Application options contains an extensive list of the configuration options, with explanations for what they do. For more advanced customization, see the Customization Guide, as well as the reference Skin options.
To install new skins, drivers, or other extensions, use the extension utility.
WeeWX must be restarted for the changes to take effect.
sudo systemctl restart weewx
sudo /etc/init.d/weewx stop
sudo /etc/init.d/weewx start
sudo service weewx stop
sudo service weewx start
sudo launchctl unload /Library/LaunchDaemons/com.weewx.weewxd.plist
sudo launchctl load /Library/LaunchDaemons/com.weewx.weewxd.plist
Upgrade¶
Get the latest release using pip:
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Upgrade the WeeWX code
python3 -m pip install weewx --upgrade
Optional: You may want to upgrade examples and utility files:
weectl station upgrade --what examples util
Optional: You may want to upgrade your skins, although this may break or remove modifications you have made to them. Your old skins will be saved in a timestamped directory.
weectl station upgrade --what skins
Optional: You may want to upgrade your configuration file. This is only necessary in the rare case that a new WeeWX release is not backward compatible with older configuration files.
weectl station upgrade --what config
Uninstall¶
Before you uninstall, be sure that weewxd is not running.
sudo systemctl stop weewx
sudo /etc/init.d/weewx stop
sudo service weewx stop
sudo launchctl unload /Library/LaunchDaemons/com.weewx.weewxd.plist
If you installed a daemon configuration, remove it:
sudo sh ~/weewx-data/scripts/setup-daemon.sh uninstall
To delete the applications and code, remove the WeeWX virtual environment:
rm -r ~/weewx-venv
Finally, if desired, to delete the database, skins, and other utilities, remove the data directory:
rm -r ~/weewx-data