Installation using pip¶
This is a guide to installing WeeWX using pip. It can be used to install WeeWX on almost any operating system, including macOS.
WeeWX V5 requires Python 3.7 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 this method, you will need them to set up a daemon, and you may need them to change device permissions.
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.
Note
WeeWX can be installed on any operating system that offers Python 3.7 or later.
However, you may need to install pip
first. See Installing pip with
Linux Package Managers. The
installation directions
on the pip website may also be useful.
You will also need venv
. If venv
is not available, you may substitute
virtualenv
, which can be installed using
pip.
Install in a virtual environment¶
To install WeeWX in a virtual environment, follow the directions below for
your system. If you plan to use MySQL or MariaDB, be sure to see the
MySQL/MariaDB
tab as well.
When finished, the WeeWX executables will have been installed in
~/weewx-venv/bin
, while the WeeWX libraries and dependencies will have been
installed in ~/weewx-venv/lib/python3.x/site-packages
, where 3.x
is the
version of Python you used.
sudo apt update
# If necessary, install pip and venv
sudo apt install python3-pip -y
sudo apt install python3-venv -y
# 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
sudo yum update
# Check your version of Python. You must have 3.7 or later
python3 -V
# If it is less than Python 3.7, install a later version of Python.
# For example, this would install Python 3.11. Afterwards, you must
# remember to invoke Python using "python3.11", NOT "python3"
sudo yum install python3.11 -y
sudo yum install python3.11-pip -y
# Create the virtual environment
python3.11 -m venv ~/weewx-venv
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment
python3.11 -m pip install weewx
sudo yum update
sudo yum install python3-pip -y
# 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
sudo zypper refresh
# Check your version of Python. You must have 3.7 or later
python3 -V
# If it is less than Python 3.7, install a later version of Python.
# For example, this would install Python 3.11. Afterwards, you must
# remember to invoke Python using "python3.11", NOT "python3"
sudo zypper install -y python311
# Create the virtual environment
python3.11 -m venv ~/weewx-venv
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment
python3.11 -m pip install weewx
# 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
# 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
If you plan on using MySQL or MariaDB with sha256_password
or
caching_sha2_password
authentication, you will also need to install
the module cryptography
. On some operating systems this can be a bit
of a struggle, but the following usually works. The key step is to update
pip before trying the install.
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Make sure pip is up-to-date
python3 -m pip install pip --upgrade
# Install cryptography
python3 -m pip install cryptography
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. It will
also install skins, documentation, utilitiy files, and examples in the same
directory. 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, run weewxd
as a daemon.
The steps to configure weewxd
to run as a daemon depend on your operating
system, and require root privileges.
# Systems that use systemd, e.g., Debian, Redhat, SUSE
sudo cp ~/weewx-data/util/systemd/weewx.service /etc/systemd/system
sudo systemctl daemon-reload
sudo systemctl enable weewx
sudo systemctl start weewx
Note
The resulting daemon will be run using your username. If you prefer to
use run as root
, you will have to modify the file
/etc/systemd/system/weewx.service
.
# Systems that use SysV init, e.g., Slackware, Devuan, Puppy, DD-WRT
sudo cp ~/weewx-data/util/init.d/weewx.debian /etc/init.d/weewx
sudo chmod +x /etc/init.d/weewx
sudo update-rc.d weewx defaults 98
sudo /etc/init.d/weewx start
Note
The resulting daemon will be run using your username. If you prefer to
use run as root
, you will have to modify the file
/etc/init.d/weewx
.
sudo cp ~/weewx-data/util/launchd/com.weewx.weewxd.plist /Library/LaunchDaemons
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 for entries from weewxd
.
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 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 customize reports, modify the configuration file. See the Customization Guide for instructions, and the application and skin references for all the options.
Use any text editor, such as nano
:
nano ~/weewx-data/weewx.conf
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 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 your documentation and examples.
weectl station upgrade --what docs 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.
If you installed a daemon configuration, remove it.
sudo systemctl stop weewx
sudo systemctl disable weewx
sudo rm /etc/systemd/system/weewx.service
sudo /etc/rc.d/init.d/weewx stop
sudo update-rc.d weewx remove
sudo rm /etc/init.d/weewx
sudo launchctl unload /Library/LaunchDaemons/com.weewx.weewxd.plist
sudo rm /Library/LaunchDaemons/com.weewx.weewxd.plist
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