2019-08-07 19:15:50 +03:00
|
|
|
[![PyPi Release](https://img.shields.io/pypi/v/maestral.svg)](https://pypi.org/project/maestral/)
|
|
|
|
[![Pyversions](https://img.shields.io/pypi/pyversions/maestral.svg)](https://pypi.org/pypi/maestral/)
|
2019-07-16 14:28:37 +03:00
|
|
|
|
2019-11-02 14:57:06 +03:00
|
|
|
# Maestral <img src="https://raw.githubusercontent.com/SamSchott/maestral-dropbox/master/maestral/gui/resources/maestral.png" align="right" title="Maestral" width="110" height="110">
|
2019-07-16 14:28:37 +03:00
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
A light-weight and open-source Dropbox client for macOS and Linux.
|
2018-11-26 18:50:02 +03:00
|
|
|
|
2018-11-26 18:56:32 +03:00
|
|
|
## About
|
2019-07-16 21:37:21 +03:00
|
|
|
|
2019-07-24 17:12:21 +03:00
|
|
|
Maestral is an open-source Dropbox client written in Python. The project's main goal is to
|
2019-07-16 21:37:21 +03:00
|
|
|
provide a client for platforms and file systems that are no longer directly supported by
|
|
|
|
Dropbox.
|
2018-11-26 18:50:02 +03:00
|
|
|
|
2019-07-16 21:37:21 +03:00
|
|
|
Currently, Maestral does not support Dropbox Paper, the management of Dropbox teams and
|
|
|
|
the management of shared folder settings. If you need any of this functionality, please
|
2019-08-23 22:56:19 +03:00
|
|
|
use the Dropbox website or the official client. As of version 0.3.0, Maestral does
|
2019-08-23 22:53:41 +03:00
|
|
|
support the syncing of multiple Dropbox accounts.
|
2019-07-16 21:37:21 +03:00
|
|
|
|
2019-10-04 23:32:24 +03:00
|
|
|
The focus on "simple" file syncing does come with advantages: on macOS, the Maestral App
|
|
|
|
bundle is 80% smaller than the official Dropbox app (50 MB vs 290 MB) and uses much less
|
2019-11-25 02:00:38 +03:00
|
|
|
memory (100 MB vs 800 MB for a medium sized Dropbox on macOS). The memory usage will
|
|
|
|
depend on the size of your synced Dropbox folder and can be further reduced when running
|
|
|
|
Maestral without a GUI.
|
2019-07-11 18:12:37 +03:00
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
## Installation
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2019-08-07 19:15:50 +03:00
|
|
|
A binary is provided for macOS High Sierra and higher and can be downloaded from the
|
2020-01-08 00:17:46 +03:00
|
|
|
Releases tab. On other platforms, please download and install the Python package from PyPI:
|
2019-06-15 22:57:17 +03:00
|
|
|
```console
|
2019-07-26 00:47:23 +03:00
|
|
|
$ python3 -m pip install --upgrade maestral
|
2019-06-15 22:57:17 +03:00
|
|
|
```
|
2020-01-08 00:17:46 +03:00
|
|
|
If you intend to use the graphical user interface, you also need to install PyQt5, either
|
|
|
|
from PyPI or from your platform's package manager.
|
|
|
|
|
|
|
|
For the Maestral daemon to integrate with systemd, please install the systemd extra:
|
2019-06-25 21:29:01 +03:00
|
|
|
```console
|
2020-01-08 00:17:46 +03:00
|
|
|
$ python3 -m pip install --upgrade maestral[systemd]
|
2019-06-25 21:29:01 +03:00
|
|
|
```
|
2020-01-08 00:17:46 +03:00
|
|
|
Details on systemd integration are given in the [Wiki](https://github.com/SamSchott/maestral-dropbox/wiki/Systemd-Integration).
|
2018-12-02 03:26:41 +03:00
|
|
|
|
2018-12-08 20:05:55 +03:00
|
|
|
## Usage
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2019-07-24 17:12:21 +03:00
|
|
|
Run `maestral gui` in the command line (or open the Maestral app on macOS) to start
|
|
|
|
Maestral with a graphical user interface. On its first run, Maestral will guide you
|
2019-07-16 21:37:21 +03:00
|
|
|
through linking and configuring your Dropbox and will then start syncing.
|
2018-12-08 15:50:42 +03:00
|
|
|
|
2019-10-02 12:58:20 +03:00
|
|
|
![screenshot macOS](https://raw.githubusercontent.com/SamSchott/maestral-dropbox/master/screenshots/macOS_dark.png)
|
2019-08-11 18:28:08 +03:00
|
|
|
![screenshot Fedora](https://raw.githubusercontent.com/SamSchott/maestral-dropbox/master/screenshots/Ubuntu.png)
|
2018-12-08 19:43:39 +03:00
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
## Command line usage
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2019-07-24 17:12:21 +03:00
|
|
|
After installation, Maestral will be available as a command line script by typing
|
2019-08-15 00:20:53 +03:00
|
|
|
`maestral` in the command prompt. Type `maestral --help` to get a full list of available
|
|
|
|
commands. The most important are:
|
2019-08-13 17:24:39 +03:00
|
|
|
|
2019-09-08 18:52:16 +03:00
|
|
|
- `maestral gui`: Starts the Maestral GUI. Creates a sync daemon if not already running.
|
2019-09-15 14:56:07 +03:00
|
|
|
- `maestral start|stop`: Starts or stops the Maestral sync daemon.
|
|
|
|
- `maestral pause|resume`: Pauses or resumes syncing.
|
2019-09-15 16:36:34 +03:00
|
|
|
- `maestral status`: Gets the current status of Maestral.
|
|
|
|
- `maestral file-status LOCAL_PATH`: Gets the sync status of an individual file or folder.
|
|
|
|
- `maestral set-dir LOCAL_PATH`: Sets the location of your local Dropbox folder.
|
2019-09-15 14:56:07 +03:00
|
|
|
- `maestral excluded add|remove|list`: Command group to manage excluded folders.
|
2019-09-15 16:36:34 +03:00
|
|
|
- `maestral ls DROPBOX_PATH`: Lists the contents of a directory on Dropbox.
|
2019-09-15 14:56:07 +03:00
|
|
|
- `maestral log show|clear|level`: Command group to manage logging.
|
2019-08-13 17:24:39 +03:00
|
|
|
|
2019-08-14 21:43:25 +03:00
|
|
|
Maestral currently supports the syncing of multiple Dropbox accounts by running multiple
|
2019-08-23 22:56:19 +03:00
|
|
|
instances. This needs to be configured from the command line. For example, before running
|
2019-08-15 00:23:58 +03:00
|
|
|
`maestral gui`, one can set up a new configuration with `maestral config new`. The
|
|
|
|
configuration name should then be given as command line option `--config-name` before
|
2019-08-14 21:43:25 +03:00
|
|
|
running maestral. For example:
|
2019-08-13 17:24:39 +03:00
|
|
|
|
|
|
|
```shell
|
2019-11-08 18:42:00 +03:00
|
|
|
$ maestral config add "personal"
|
|
|
|
$ maestral config add "work"
|
2019-08-13 17:24:39 +03:00
|
|
|
$ maestral gui --config-name="personal"
|
|
|
|
$ maestral gui --config-name="work"
|
2018-12-02 03:26:41 +03:00
|
|
|
```
|
2019-08-15 00:23:58 +03:00
|
|
|
This will start two instances of Maestral, syncing a private and a work account,
|
2019-08-14 21:43:25 +03:00
|
|
|
respectively. Multiple Maestral daemons are supported as well.
|
|
|
|
|
|
|
|
By default, the Dropbox folder names will contain the capitalised config-name in braces.
|
|
|
|
In the above case, this will be "Dropbox (Personal)" and "Dropbox (Work)".
|
2019-06-15 22:57:17 +03:00
|
|
|
|
|
|
|
## Contribute
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2019-06-26 22:09:37 +03:00
|
|
|
The following tasks could need your help:
|
2019-06-15 22:57:17 +03:00
|
|
|
|
2019-08-14 21:43:25 +03:00
|
|
|
- [ ] Write tests for Maestral.
|
2019-06-25 21:29:01 +03:00
|
|
|
- [ ] Detect and warn in case of unsupported Dropbox folder locations (network drives,
|
2019-08-07 19:15:50 +03:00
|
|
|
external hard drives, etc).
|
2019-07-09 21:27:49 +03:00
|
|
|
- [ ] Native Cocoa and GTK interfaces. Maestral currently uses PyQt5.
|
2019-07-16 21:37:21 +03:00
|
|
|
- [ ] Packaging: improve packing for macOS (reduce app size) and package for other platforms.
|
2018-11-28 00:29:49 +03:00
|
|
|
|
2018-12-02 03:26:41 +03:00
|
|
|
## Warning:
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2019-08-15 17:48:16 +03:00
|
|
|
- Maestral is still in beta status. Even though highly unlikely, using it may potentially
|
2019-07-09 21:27:49 +03:00
|
|
|
result in loss of data.
|
2019-08-07 19:15:50 +03:00
|
|
|
- Network drives and some external hard drives are not supported as locations for the
|
|
|
|
Dropbox folder.
|
2018-11-28 00:23:00 +03:00
|
|
|
|
|
|
|
## Dependencies
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2019-08-14 21:43:25 +03:00
|
|
|
- macOS (10.13 or higher for binary) or Linux
|
2019-07-09 19:19:49 +03:00
|
|
|
- Python 3.6 or higher
|
2019-08-14 21:43:25 +03:00
|
|
|
- For the GUI only:
|
|
|
|
- PyQt 5.9 or higher
|
|
|
|
- [gnome-shell-extension-appindicator](https://github.com/ubuntu/gnome-shell-extension-appindicator)
|
|
|
|
on Gnome 3.26 and higher
|
2019-07-22 19:22:22 +03:00
|
|
|
|
|
|
|
# Acknowledgements
|
|
|
|
|
|
|
|
- The config module uses code from the [Spyder IDE](https://github.com/spyder-ide).
|
|
|
|
- The MaestralApiClient is based on the work from [Orphilia](https://github.com/ksiazkowicz/orphilia-dropbox).
|
2020-01-08 17:22:37 +03:00
|
|
|
- Error reporting is powered by [bugsnag](https://bugsnag.com):
|
|
|
|
|
|
|
|
<img src="https://global-uploads.webflow.com/5c741219fd0819540590e785/5c7fab2b4e3feefc6bd8f0ce_5c7e8ad810414d05694fe4d8_asset%203.svg" align="left" title="Bugsnag logo" height="30"><img src="https://global-uploads.webflow.com/5c741219fd0819540590e785/5c741219fd0819856890e790_asset%2039.svg" align="left" title="Bugsnag text" height="40">
|
|
|
|
|